> ## Documentation Index
> Fetch the complete documentation index at: https://developers.cloudtalk.io/llms.txt
> Use this file to discover all available pages before exploring further.
# CloudTalk Webhooks
> CloudTalk webhooks push real-time events (calls, contacts, users, messages, and AI insights) to your HTTPS endpoint as signed JSON, so you can react without polling.
Webhooks notify your systems the moment something happens in CloudTalk. Instead of polling the API, you register an HTTPS endpoint and CloudTalk sends it a signed JSON `POST` for every event you subscribe to: a call starting, a contact changing, a transcript becoming ready.
These pages describe the account-level webhooks you set up under **Account → Webhooks** in the CloudTalk Dashboard. Several other CloudTalk features can also call an endpoint you own, including the **Webhook** step in Call Flow Designer, the **Send via Webhook** option on an AI Voice Agent, and Workflow Automation actions. Those send their own payloads over their own delivery path: they are not signed with the scheme described here, and the retry, replay and retention behaviour on these pages does not apply to them.
The full call lifecycle: from first ring to finished recording.
Keep contact data in sync with your CRM.
Team changes and live user availability.
Inbound and outbound SMS, MMS, and WhatsApp.
Transcripts, summaries, sentiment, topics, talk ratio, and call scores.
Structured data captured by AI Voice Agents.
Dispositions and survey responses from Dialer campaigns.
## Set up your first webhook
Webhooks are available on the **Essential** plan and higher. They are managed in the CloudTalk Dashboard under **Account → Webhooks**; you need an **Admin** role to see it.
1. Go to **Account → Webhooks** and click **Add endpoint**. Enter the **HTTPS URL** your endpoint listens on and, optionally, a description.
2. Choose the **event types** to subscribe to. Leave the selection empty to receive every event type, including ones added in the future.
3. Open the new endpoint and reveal its **signing secret**. Store it in your handler's configuration and [verify signatures](/guides/webhooks/verify-signatures) on every delivery.
4. Click **Send test event**, pick an event type, and confirm your endpoint responds with a `2xx`. The attempt (and every real delivery after it) appears in the endpoint's **delivery log**.
From the same page you can later edit the URL or subscriptions, **rotate** the signing secret, **disable** or re-enable the endpoint, **resend** a single delivery, or **recover** every failed delivery since a chosen time.
Your endpoint must be reachable over **HTTPS** and should respond with a `2xx` quickly. See [delivery and retries](/guides/webhooks/delivery) for how CloudTalk handles slow or failing endpoints.
If you don't see **Webhooks** under **Account**, either your role isn't Admin or your plan is below Essential. Your account manager can help with either.
## The event envelope
Every webhook arrives with the same top-level structure; only `data` differs per event type. Every envelope field is always present.
```json theme={"system"}
{
"event_id": "3f9a2b4c-8d1e-8a2b-9c3d-4e5f60718293",
"type": "contact.created",
"version": "v1",
"occurred_at": "2026-08-17T09:34:21.512Z",
"company_id": "123456",
"data": {
"id": "44210",
"name": "Jane Doe",
"company": "Acme Inc.",
"phones": ["+12025550143"],
"emails": ["jane.doe@example.com"],
"tags": ["vip", "priority"],
"created_at": "2026-08-17T09:34:21Z"
}
}
```
| Field | Type | Description |
| ------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `event_id` | string | A unique, stable id for this event (UUID). Deliveries are at-least-once, so the same event can occasionally arrive twice, always with the same `event_id`. De-duplicate on it. |
| `type` | string | The event type as `resource.action`, for example `call.started` or `contact.updated`. Route on this, and ignore types you don't recognize: new event types are added over time. |
| `version` | string | The payload version for this event type, for example `v1`. Versions bump only on breaking changes; new optional fields can appear within a version, so tolerate unknown fields. |
| `occurred_at` | string | When the event happened: RFC 3339, always UTC. Delivery order is not guaranteed, so sort by this field. |
| `company_id` | string | Your CloudTalk account id. |
| `data` | object | The event's details. The shape is defined per `type` and `version`. See the event pages. |
Fields with empty values are omitted from `data` rather than sent as `null`. Treat a missing optional field as empty.
## Event catalogue
| Event | Fires when |
| ----------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
| [`call.started`](/guides/webhooks/events/calls#call-started) | A call begins, before anyone picks up |
| [`call.ringing`](/guides/webhooks/events/calls#call-ringing) | A call rings on a specific user |
| [`call.answered`](/guides/webhooks/events/calls#call-answered) | A call is picked up |
| [`call.held`](/guides/webhooks/events/calls#call-held) | A call is placed on hold |
| [`call.resumed`](/guides/webhooks/events/calls#call-resumed) | A call is taken off hold |
| [`call.ended`](/guides/webhooks/events/calls#call-ended) | A call finishes, with final details |
| [`call.recording_ready`](/guides/webhooks/events/calls#call-recording-ready) | A recording (or voicemail) is stored (async, after `call.ended`) |
| [`call.tags_modified`](/guides/webhooks/events/calls#call-tags-modified) | Tags are added to or removed from a call |
| [`contact.created`](/guides/webhooks/events/contacts#contact-created) | A contact is added |
| [`contact.updated`](/guides/webhooks/events/contacts#contact-updated) | A contact changes: full current profile |
| [`contact.deleted`](/guides/webhooks/events/contacts#contact-deleted) | A contact is removed: id only |
| [`user.created`](/guides/webhooks/events/users#user-created) | A user is added |
| [`user.updated`](/guides/webhooks/events/users#user-updated) | A user's profile changes: full current profile |
| [`user.deleted`](/guides/webhooks/events/users#user-deleted) | A user is removed: id only |
| [`user.status_changed`](/guides/webhooks/events/users#user-status-changed) | A user's availability changes |
| [`message.sent`](/guides/webhooks/events/messages#message-sent) | A message (SMS, MMS, or WhatsApp) is sent from your number |
| [`message.received`](/guides/webhooks/events/messages#message-received) | A message (SMS, MMS, or WhatsApp) arrives on your number |
| [`transcript.ready`](/guides/webhooks/events/conversation-intelligence#transcript-ready) | A call transcript is available |
| [`cidata.ready`](/guides/webhooks/events/conversation-intelligence#cidata-ready) | AI analysis (summary, sentiment, topics, talk ratio, call score) is ready |
| [`voice_agent.extracted_data_ready`](/guides/webhooks/events/voice-agents#voice_agent-extracted_data_ready) | An AI Voice Agent hands over extracted data |
| [`dialer.disposition_created`](/guides/webhooks/events/dialer#dialer-disposition-created) | A user records a disposition on a Dialer call |
| [`dialer.survey_filled`](/guides/webhooks/events/dialer#dialer-survey-filled) | A user submits a survey response on a Dialer call |
## Delivery guarantees at a glance
* **At-least-once**: rare duplicates carry the same `event_id`; de-duplicate on it.
* **No ordering guarantee**: sort by `occurred_at`.
* **Signed**: every delivery carries signature headers; [verify them](/guides/webhooks/verify-signatures).
* **Retried**: a failed delivery is retried up to 50 times over \~11.5 hours. An endpoint that fails continuously for \~5 days is disabled, then automatically re-enabled if it recovers within 12 hours. See [delivery and retries](/guides/webhooks/delivery).
* **Retained 30 days**: event payloads stay available to view, resend or recover for 30 days.
## Next steps
Authenticate every delivery before trusting it.
Timeouts, the retry schedule, and best practices for reliable handlers.
## Related topics
- [How to Verify CloudTalk Webhook Signatures](/guides/webhooks/verify-signatures.md)
- [CloudTalk Webhook Delivery, Retries, and Best Practices](/guides/webhooks/delivery.md)
- [CloudTalk MCP](/guides/mcp/overview.md)