chatrail-dev Webhooks API

openapi: 3.2.0
info:
  title: ChatRail Webhooks API
  version: 1.0.0
  description: 'Send, schedule and receive WhatsApp messages through a linked-device session.


    **Two things the API is careful about, which shape every endpoint below.**


    *Accepted is not delivered.* A 202 means the message is durably stored and queued. Only the `status` field ever claims WhatsApp delivered anything, and `queued`, `submitted`, `sent`, `delivered` and `read` are deliberately distinct.


    *A retry must not send twice.* Send `Idempotency-Key` on every send. A replay returns the original response; a concurrent duplicate is told to retry rather than allowed to race.'
  contact:
    name: ChatRail
    url: https://www.chatrail.dev
servers:
- url: https://www.chatrail.dev
security:
- apiKey: []
tags:
- name: Webhooks
  description: Where inbound events and delivery updates are sent.
paths:
  /v1/webhook-endpoints:
    post:
      summary: Register a webhook endpoint
      description: Returns the signing secret **exactly once**. Every delivery is signed with HMAC-SHA256 over the timestamp, a period, and the raw request body; verify it and reject stale timestamps. The URL is validated at registration and the connection pinned at delivery, so an endpoint pointing at a private address is refused. Works with an API key holding `webhooks:write`, so a deploy script can register its own endpoint; every change is audited.
      tags:
      - Webhooks
      operationId: post_v1_webhook-endpoints
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                url:
                  type: string
                  maxLength: 2048
                  format: uri
                description:
                  type: string
                  maxLength: 200
                events:
                  minItems: 1
                  maxItems: 46
                  type: array
                  items:
                    type: string
                connection:
                  type: string
                  minLength: 1
                  maxLength: 40
              required:
              - url
              - events
              additionalProperties: false
            example:
              url: https://example.com/hooks/chatrail
              events:
              - message.received
              - message.delivered
              - message.failed
              description: Order updates
      responses:
        '201':
          description: Created, with the one-time signing secret.
        '400':
          description: The URL is not publicly reachable over https.
        '402':
          description: Scoping to one connection is not on this plan.
      security:
      - apiKey:
        - webhooks:write
      - session: []
      x-scopes:
      - webhooks:write
    get:
      summary: List webhook endpoints
      tags:
      - Webhooks
      operationId: get_v1_webhook-endpoints
      responses:
        '200':
          description: Endpoints, without their signing secrets.
      security:
      - apiKey:
        - webhooks:read
      - session: []
      x-scopes:
      - webhooks:read
  /v1/webhook-endpoints/{id}:
    delete:
      summary: Delete a webhook endpoint
      tags:
      - Webhooks
      operationId: delete_v1_webhook-endpoints__id_
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: Endpoint id.
      responses:
        '204':
          description: Deleted.
        '404':
          description: No such endpoint.
      security:
      - apiKey:
        - webhooks:write
      - session: []
      x-scopes:
      - webhooks:write
  /v1/webhook-endpoints/{id}/enable:
    post:
      summary: Re-enable a webhook endpoint
      description: Turns back on an endpoint that was disabled after 50 failed deliveries in a row. The failure count restarts at zero and the signing secret is unchanged. Events skipped while it was disabled are not re-sent.
      tags:
      - Webhooks
      operationId: post_v1_webhook-endpoints__id__enable
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: Endpoint id.
      responses:
        '200':
          description: The endpoint, now active.
        '404':
          description: No such endpoint.
      security:
      - apiKey:
        - webhooks:write
      - session: []
      x-scopes:
      - webhooks:write
components:
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      description: 'A workspace API key, `cr_live_…`. Server-side only: it carries workspace authority and must never reach a browser.'
    session:
      type: apiKey
      in: cookie
      name: chatrail_session
      description: Dashboard session cookie. Set by `/v1/auth/verify`.