> ## Documentation Index
> Fetch the complete documentation index at: https://help.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.

> [!NOTE]
>
> These pages describe the account-level webhooks you set up under **Settings → 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.

> [card] [Call events](https://help.cloudtalk.io/guides/webhooks/events/calls.md)
>
> The full call lifecycle: from first ring to finished recording.

> [card] [Contact events](https://help.cloudtalk.io/guides/webhooks/events/contacts.md)
>
> Keep contact data in sync with your CRM.

> [card] [User events](https://help.cloudtalk.io/guides/webhooks/events/users.md)
>
> Team changes and live user availability.

> [card] [Message events](https://help.cloudtalk.io/guides/webhooks/events/messages.md)
>
> Inbound and outbound SMS, MMS, and WhatsApp.

> [card] [Conversation Intelligence](https://help.cloudtalk.io/guides/webhooks/events/conversation-intelligence.md)
>
> Transcripts, summaries, sentiment, topics, talk ratio, and call scores.

> [card] [AI Voice Agents](https://help.cloudtalk.io/guides/webhooks/events/voice-agents.md)
>
> Structured data captured by AI Voice Agents.

> [card] [Dialer](https://help.cloudtalk.io/guides/webhooks/events/dialer.md)
>
> 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 **Settings → Webhooks**; you need an **Admin** role to see it.

1. Go to **Settings → 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](https://help.cloudtalk.io/guides/webhooks/verify-signatures.md) 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.

Prefer code to clicks? Everything on this page, except recovering a range of failed deliveries, is also available from the API: see [Manage webhooks with the API](https://help.cloudtalk.io/guides/webhooks/manage-with-api.md).

Your endpoint must be reachable over **HTTPS** and should respond with a `2xx` quickly. See [delivery and retries](https://help.cloudtalk.io/guides/webhooks/delivery.md) for how CloudTalk handles slow or failing endpoints.

> [!NOTE]
>
> 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. |

> [!NOTE]
>
> 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`](https://help.cloudtalk.io/guides/webhooks/events/calls#call-started) | A call begins, before anyone picks up |
| [`call.ringing`](https://help.cloudtalk.io/guides/webhooks/events/calls#call-ringing) | A call rings on a specific user |
| [`call.answered`](https://help.cloudtalk.io/guides/webhooks/events/calls#call-answered) | A call is picked up |
| [`call.held`](https://help.cloudtalk.io/guides/webhooks/events/calls#call-held) | A call is placed on hold |
| [`call.resumed`](https://help.cloudtalk.io/guides/webhooks/events/calls#call-resumed) | A call is taken off hold |
| [`call.ended`](https://help.cloudtalk.io/guides/webhooks/events/calls#call-ended) | A call finishes, with final details |
| [`call.recording_ready`](https://help.cloudtalk.io/guides/webhooks/events/calls#call-recording_ready) | A recording (or voicemail) is stored (async, after `call.ended`) |
| [`call.completed`](https://help.cloudtalk.io/guides/webhooks/events/calls#call-completed) | A call's post-call data, in one event: once everything expected has arrived, or 30 minutes after the call ended |
| [`call.tags_modified`](https://help.cloudtalk.io/guides/webhooks/events/calls#call-tags_modified) | Tags are added to or removed from a call |
| [`contact.created`](https://help.cloudtalk.io/guides/webhooks/events/contacts#contact-created) | A contact is added |
| [`contact.updated`](https://help.cloudtalk.io/guides/webhooks/events/contacts#contact-updated) | A contact changes: full current profile |
| [`contact.deleted`](https://help.cloudtalk.io/guides/webhooks/events/contacts#contact-deleted) | A contact is removed: id only |
| [`user.created`](https://help.cloudtalk.io/guides/webhooks/events/users#user-created) | A user is added |
| [`user.updated`](https://help.cloudtalk.io/guides/webhooks/events/users#user-updated) | A user's profile changes: full current profile |
| [`user.deleted`](https://help.cloudtalk.io/guides/webhooks/events/users#user-deleted) | A user is removed: id only |
| [`user.status_changed`](https://help.cloudtalk.io/guides/webhooks/events/users#user-status_changed) | A user's availability changes |
| [`message.sent`](https://help.cloudtalk.io/guides/webhooks/events/messages#message-sent) | A message (SMS, MMS, or WhatsApp) is sent from your number |
| [`message.received`](https://help.cloudtalk.io/guides/webhooks/events/messages#message-received) | A message (SMS, MMS, or WhatsApp) arrives on your number |
| [`message.delivery_updated`](https://help.cloudtalk.io/guides/webhooks/events/messages#message-delivery_updated) | The delivery status of a message sent from your number changes, for example to delivered or failed |
| [`transcript.ready`](https://help.cloudtalk.io/guides/webhooks/events/conversation-intelligence#transcript-ready) | A call transcript is available |
| [`cidata.ready`](https://help.cloudtalk.io/guides/webhooks/events/conversation-intelligence#cidata-ready) | AI analysis (summary, sentiment, topics, talk ratio, call score) is ready |
| [`voice_agent.extracted_data_ready`](https://help.cloudtalk.io/guides/webhooks/events/voice-agents#voice_agent-extracted_data_ready) | An AI Voice Agent hands over extracted data |
| [`dialer.disposition_created`](https://help.cloudtalk.io/guides/webhooks/events/dialer#dialer-disposition_created) | A user records a disposition on a Dialer call |
| [`dialer.survey_filled`](https://help.cloudtalk.io/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](https://help.cloudtalk.io/guides/webhooks/verify-signatures.md).
* **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](https://help.cloudtalk.io/guides/webhooks/delivery.md).
* **Retained 30 days**: event payloads stay available to view, resend or recover for 30 days.

## Next steps

> [card] [Verify signatures](https://help.cloudtalk.io/guides/webhooks/verify-signatures.md)
>
> Authenticate every delivery before trusting it.

> [card] [Delivery and retries](https://help.cloudtalk.io/guides/webhooks/delivery.md)
>
> Timeouts, the retry schedule, and best practices for reliable handlers.

> [card] [Manage with the API](https://help.cloudtalk.io/guides/webhooks/manage-with-api.md)
>
> Create endpoints, rotate secrets and inspect deliveries from your own code.


## Related topics

- [How to Verify CloudTalk Webhook Signatures](https://help.cloudtalk.io/guides/webhooks/verify-signatures.md)
- [CloudTalk Webhook Delivery, Retries, and Best Practices](https://help.cloudtalk.io/guides/webhooks/delivery.md)
- [Send CloudTalk SMS from Pipedrive via Automation](https://help.cloudtalk.io/en/articles/14594584-send-cloudtalk-sms-from-pipedrive-via-automation.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.