Webhooks

handoff_requested

A human took over a conversation from the AI — either a takeover was recorded, or AI handling was switched off. reason is whatever was given at takeover, and is often null when the AI was simply toggled off.

postWebhookhandoff_requested

Payload

eventstring

Event type. Also sent in the X-Webhook-Event header.

timestampstring date-time

When the event was delivered — not necessarily when it occurred.

webhook_idstring uuid

Delivery ID. Also sent as X-Webhook-ID. Use it to deduplicate retries.

organization_idstring uuid

Example payload

{
  "event": "contact_created"
}

Response

Return any 2xx to acknowledge. A non-2xx or a timeout is treated as a failed delivery and retried with backoff up to your configured max_retries.

Changes

Webhooks have no change history: a webhook is keyed by its event name rather than a path and method, so no recorded change can name it.