CloudTalk Webhooks

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.

Call events

The full call lifecycle: from first ring to finished recording.

Contact events

Keep contact data in sync with your CRM.

User events

Team changes and live user availability.

Message events

Inbound and outbound SMS, MMS, and WhatsApp.

Conversation Intelligence

Transcripts, summaries, sentiment, topics, talk ratio, and call scores.

AI Voice Agents

Structured data captured by AI Voice Agents.

Dialer

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.

Go to Account → Webhooks and click Add endpoint. Enter the HTTPS URL your endpoint listens on and, optionally, a description.
Choose the event types to subscribe to. Leave the selection empty to receive every event type, including ones added in the future.
Open the new endpoint and reveal its signing secret. Store it in your handler’s configuration and verify signatures on every delivery.
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 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.

{
  "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`	A call begins, before anyone picks up
`call.ringing`	A call rings on a specific user
`call.answered`	A call is picked up
`call.held`	A call is placed on hold
`call.resumed`	A call is taken off hold
`call.ended`	A call finishes, with final details
`call.recording_ready`	A recording (or voicemail) is stored (async, after `call.ended`)
`call.tags_modified`	Tags are added to or removed from a call
`contact.created`	A contact is added
`contact.updated`	A contact changes: full current profile
`contact.deleted`	A contact is removed: id only
`user.created`	A user is added
`user.updated`	A user’s profile changes: full current profile
`user.deleted`	A user is removed: id only
`user.status_changed`	A user’s availability changes
`message.sent`	A message (SMS, MMS, or WhatsApp) is sent from your number
`message.received`	A message (SMS, MMS, or WhatsApp) arrives on your number
`transcript.ready`	A call transcript is available
`cidata.ready`	AI analysis (summary, sentiment, topics, talk ratio, call score) is ready
`voice_agent.extracted_data_ready`	An AI Voice Agent hands over extracted data
`dialer.disposition_created`	A user records a disposition on a Dialer call
`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.
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.
Retained 30 days: event payloads stay available to view, resend or recover for 30 days.

Getting Started

Events

CloudTalk Webhooks

Call events

Contact events

User events

Message events

Conversation Intelligence

AI Voice Agents

Dialer

Set up your first webhook

The event envelope

Event catalogue

Delivery guarantees at a glance

Next steps

Verify signatures

Delivery and retries

Call events

Contact events

User events

Message events

Conversation Intelligence

AI Voice Agents

Dialer

​Set up your first webhook

​The event envelope

​Event catalogue

​Delivery guarantees at a glance

​Next steps

Verify signatures

Delivery and retries

Set up your first webhook

The event envelope

Event catalogue

Delivery guarantees at a glance

Next steps