Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we
store it to create your key and to recognise you if you sign in with another
provider. By signing up you are subscribing to the APIs.io and API Evangelist
newsletters — you can unsubscribe from any issue. See our
Privacy Policy and Terms.
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`.