Webhook Schema

This reference documents the event payloads the CRM delivers to your registered Webhook Event URL. See the Webhooks overview for delivery mechanics, signature verification, retry behavior, and idempotency.

All events share a common top-level envelope:

{
  "id": "9a0e8400-e29b-41d4-a716-446655440020",
  "event": "message.created",
  "created_at": "2026-01-15T10:05:00Z",
  "data": { }
}

Route on the event field. Use the id as your idempotency key: it is stable across retried deliveries.

conversation.created

Fired when a new conversation is opened in a workspace. Use this event to initialize any conversation-level state your app maintains (e.g. CRM record creation, ticket linking).

conversation.state-changed

Fired when a conversation transitions between states (e.g. open → resolved, resolved → open). Use changed_at in the payload to order events if out-of-order delivery occurs.

conversation.assigned

Fired when a conversation is assigned to an agent, bot, or team. The payload identifies the assignee type and ID so your app can route or notify accordingly.

message.created

Fired when a new message appears in a conversation, regardless of sender. This fires for messages from contacts, agents, and bots. Use sender.type in the payload to distinguish the source.

message.sent

Fired after the CRM successfully delivers an outbound message to its channel (e.g. Telegram). The data.request_id field matches the request_id returned in the 202 Accepted response from POST /v1/conversations/{id}/messages. See Message Delivery Status for correlation details.

message.failed

Fired when an outbound message delivery fails. The payload includes an error object with a human-readable message and a machine-readable slug. The data.request_id field matches the original send request. See Message Delivery Status for correlation details.