Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.clerk.chat/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

Webhooks let your application subscribe to events on your Clerk Chat workspace and receive an HTTP POST whenever those events occur — for example, when a message is sent, delivered, or received, or when a contact taps an RCS suggestion. You register a URL, choose which event types you care about, and Clerk Chat delivers a JSON payload to that URL with retries and signature headers.

​
Register a webhook

Webhooks are managed from the Clerk Chat dashboard:
  1. Sign in at app.clerk.chat.
  2. Open Settings → Webhooks.
  3. Click Add webhook and fill in:
    • Name — a human-friendly label.
    • URL — the https:// endpoint Clerk Chat will POST to.
    • Event types — the events you want to subscribe to (see below).
    • Auth header (optional) — a custom header name and value that Clerk Chat will send with each delivery so you can verify requests on your side. Defaults to Authorization if you only provide a value.
  4. Save. The webhook is enabled immediately.
From the same screen you can edit a webhook, toggle it on/off, delete it, or open a webhook to inspect recent delivery attempts.

​
Event types

EventWhen it fires
message.sentAn outbound message has been accepted by the carrier.
message.deliveredAn outbound message was delivered to the recipient’s device.
message.failedAn outbound message failed to send.
message.readA recipient has read an outbound message (where supported).
message.receivedAn inbound message arrived in one of your inboxes.
rcsPostbackReceivedA contact tapped an RCS suggestion (quick reply or action).

​
Payload

Every delivery is a POST with Content-Type: application/json and a body shaped like: 
{
  "eventId": "5b8c4f1e-2c3a-4f1e-9d8a-7e6b5a4c3d2f",
  "type": "message.received",
  "teamId": "f1e2d3c4-b5a6-7890-1234-56789abcdef0",
  "occurredAt": "2026-05-08T17:42:11.123Z",
  "data": {
    "conversationId": "...",
    "inboxId": "...",
    "channel": "sms",
    "direction": "inbound",
    "from": "+15551234567",
    "to": "+15557654321",
    "body": "Hello!",
    "status": "received"
  }
}
The shape of data depends on type. Message events carry conversation, inbox, channel, direction, addresses, body, and status. RCS postbacks carry the suggestion id, suggestion text, template id, and the messageId that was tapped.

​
Headers

Each request includes:
HeaderDescription
User-AgentClerkChat-Webhooks/1
X-ClerkChat-Event-IdStable id for this event — use it to deduplicate.
X-ClerkChat-Event-TypeSame value as type in the body.
X-ClerkChat-Delivery-IdUnique id for this delivery attempt.
X-ClerkChat-AttemptZero-based attempt index (0 on the first try).
If you configured an auth header, it is included on every request — verify it on your side before trusting the payload.

​
Responding to deliveries

  • Reply with any 2xx status code to acknowledge the delivery.
  • Anything else (non-2xx, network error, or redirect) is treated as a failure.
  • Requests time out after 10 seconds, so do any heavy work asynchronously and respond quickly.
  • Redirects are not followed — give us the final URL.

​
Retries and auto-disable

Failed deliveries are retried up to 5 times with exponential backoff, starting at ~2 minutes. You can see each attempt and its status under the webhook’s deliveries view in the dashboard. If a webhook accumulates 5 consecutive failed deliveries (each having exhausted its retries), Clerk Chat automatically disables it so we stop hammering a broken endpoint. Re-enable it from Settings → Webhooks once your endpoint is healthy. A successful delivery resets the failure counter, so transient blips won’t disable a webhook on their own.

​
Idempotency

Use eventId (also sent as X-ClerkChat-Event-Id) as your idempotency key. Clerk Chat won’t deliver the same eventId to the same webhook twice, but retries reuse the same eventId, so your handler should be safe to invoke more than once per event.