CleverStack can send an event to your server at every step of a call: when it starts, rings, is answered and ends, when the call record, recording and transcript are ready, and when the outcome is saved. It also sends WhatsApp message events and AI Agent events. This page lists every event, how delivery works, and a sample body for each.
All names, numbers, ids and links in the examples on this page are sample values. Your events carry your own values.
Getting started
Create a webhook, learn how events reach your server, and pick the groups of events you need.
Set up a webhook
How to
Open Developer › Webhooks in the console.
Click Create Webhook and enter the HTTPS URL on your server that should receive events.
Tick the events you want. The picker lists them in the groups below; a webhook receives only the events it is subscribed to.
Save, then place a test call and check that your server answers with a 2xx status.
How delivery works
Method and body
The method set on the webhook (normally POST) with a JSON body. Any static body fields you add to the webhook are merged into every body.
Join key
call_uuid (and trace_id, same value) is identical on every event of one call. On WhatsApp, trace_id is the message id.
Duplicates
Delivery is at least once. The X-Webhook-Id header is the same on a repeat delivery: store it and drop events you have already processed.
Organisation
Every delivery carries the header X-Org-Id with your organisation id (a UUID). AI Agent events also carry it in the body as org_uuid.
Success
Any 2xx response, within 10 seconds. Do slow work after you reply.
Retries
Any other response (including 4xx), a timeout or a network error is retried: 8 attempts in total, after 1 min, 4 min, 10 min, 30 min, 1 h, 4 h and 6 h, about 12 hours in all. After the last attempt the delivery shows as failed in the webhook logs in the console.
Order
Events can arrive out of order. Sort by timestamp and join on trace_id.
Timestamps
UTC, ISO 8601 with Z, for example 2026-11-19T10:00:00.000000Z.
New fields
We may add fields. We never rename or remove one. Ignore fields you do not know.
Item
Behaviour
Method and body
The method set on the webhook (normally POST) with a JSON body. Any static body fields you add to the webhook are merged into every body.
Join key
call_uuid (and trace_id, same value) is identical on every event of one call. On WhatsApp, trace_id is the message id.
Duplicates
Delivery is at least once. The X-Webhook-Id header is the same on a repeat delivery: store it and drop events you have already processed.
Organisation
Every delivery carries the header X-Org-Id with your organisation id (a UUID). AI Agent events also carry it in the body as org_uuid.
Success
Any 2xx response, within 10 seconds. Do slow work after you reply.
Retries
Any other response (including 4xx), a timeout or a network error is retried: 8 attempts in total, after 1 min, 4 min, 10 min, 30 min, 1 h, 4 h and 6 h, about 12 hours in all. After the last attempt the delivery shows as failed in the webhook logs in the console.
Order
Events can arrive out of order. Sort by timestamp and join on trace_id.
Timestamps
UTC, ISO 8601 with Z, for example 2026-11-19T10:00:00.000000Z.
New fields
We may add fields. We never rename or remove one. Ignore fields you do not know.
Event groups
Every event belongs to one group. Each group has its own part of this page.
Each conversation an AI agent handles, on calls and WhatsApp, from start to result.
Call events
Every step of a call, its record, recording and transcript. Inbound and outbound calls send the same events with the same fields: tell them apart by call_type and call_mode. Join the events of one call on call_uuid.
At a glance
CALL_INITIATED
When it is sent: A call is created. On inbound calls: when the first agent is rung
Outbound: Yes
Inbound: When an agent is rung
AI agent call: Outbound only
CALL_RINGING
When it is sent: The first agent's phone rings. Not sent for click-to-call
Outbound: Yes, except click-to-call
Inbound: When an agent is rung
AI agent call: Outbound only
CALL_ANSWERED
When it is sent: A party answers: the customer (on inbound, when your call flow answers) and each agent who picks up
Outbound: Yes
Inbound: Yes
AI agent call: Yes
CALL_COMPLETED
When it is sent: A party's leg ends: once per party
Outbound: Yes
Inbound: Yes
AI agent call: Yes
CALL_CDR
When it is sent: The call record, a few seconds after the call ends. Once per call
Outbound: Yes
Inbound: Yes
AI agent call: Yes
CALL_RECORDING
When it is sent: The call's recording is published, and again when it changes
Outbound: Yes
Inbound: Yes
AI agent call: Yes
TRANSCRIPTION_COMPLETED
When it is sent: The transcript and analysis are ready, seconds to a minute after the call
Outbound: With Post-call insights
Inbound: With Post-call insights
AI agent call: Yes
Event
When it is sent
Outbound
Inbound
AI agent call
CALL_INITIATED
A call is created. On inbound calls: when the first agent is rung
Yes
When an agent is rung
Outbound only
CALL_RINGING
The first agent's phone rings. Not sent for click-to-call
Yes, except click-to-call
When an agent is rung
Outbound only
CALL_ANSWERED
A party answers: the customer (on inbound, when your call flow answers) and each agent who picks up
Yes
Yes
Yes
CALL_COMPLETED
A party's leg ends: once per party
Yes
Yes
Yes
CALL_CDR
The call record, a few seconds after the call ends. Once per call
Yes
Yes
Yes
CALL_RECORDING
The call's recording is published, and again when it changes
Yes
Yes
Yes
TRANSCRIPTION_COMPLETED
The transcript and analysis are ready, seconds to a minute after the call
With Post-call insights
With Post-call insights
Yes
Event order
Events can arrive out of order, so treat these sequences as a guide, not a rule.
Inbound: the call flow answers, then an agent is rung and picks up
1. CALL_ANSWERED (customer)
2. CALL_INITIATED (agent)
3. CALL_RINGING (agent)
4. CALL_ANSWERED (agent)
5. CALL_COMPLETED (customer)
6. CALL_COMPLETED (agent)
7. CALL_CDR
Outbound click-to-call: the agent's phone is called first, then the customer
1. CALL_INITIATED (agent)
2. CALL_ANSWERED (agent)
3. CALL_ANSWERED (customer)
4. CALL_COMPLETED (customer)
5. CALL_COMPLETED (agent)
6. CALL_CDR
Inbound that never rings an agent (ends in the call flow or with an AI agent)
These four events share one body. Each one is about one party's leg of the call, named in participant.
event
Type: string
Meaning: The event name.
call_uuid
Type: string
Meaning: The call's id. The same on every event of one call.
trace_id
Type: string
Meaning: Same value as call_uuid.
call_mode
Type: string
Meaning: incoming on inbound; click_to_call, manual, preview, progressive or call_flow on outbound.
call_type
Type: string
Meaning: inbound for calls to your number, outbound for calls you place. Same events and fields either way.
status
Type: string
Meaning: initiated, ringing, customer_answered or agent_answered, completed.
participant
Type: string
Meaning: Whose leg the event is about: customer or agent (call on CALL_CDR).
agent_id
Type: string | null
Meaning: The agent's user id. null when no person is on the leg (call flow, AI agent).
agent_number
Type: string | null
Meaning: The agent's phone or extension on an agent's leg; null on any leg with no person on it (the customer's leg, a call flow, an AI agent). CALL_CDR carries the agent's extension.
customer_number
Type: string
Meaning: The customer's number in E.164 format.
cli_number
Type: string
Meaning: Your CleverStack number: the number dialled on inbound, the caller ID on outbound.
recording_url
Type: string | null
Meaning: Present once recording has started. The full link is on CALL_COMPLETED and on CALL_CDR.
timestamp
Type: string
Meaning: When the event happened (UTC).
metadata
Type: object
Meaning: On calls started through the click-to-call API: the metadata you sent, returned unchanged on every lifecycle event.
Field
Type
Meaning
event
string
The event name.
call_uuid
string
The call's id. The same on every event of one call.
trace_id
string
Same value as call_uuid.
call_mode
string
incoming on inbound; click_to_call, manual, preview, progressive or call_flow on outbound.
call_type
string
inbound for calls to your number, outbound for calls you place. Same events and fields either way.
status
string
initiated, ringing, customer_answered or agent_answered, completed.
participant
string
Whose leg the event is about: customer or agent (call on CALL_CDR).
agent_id
string | null
The agent's user id. null when no person is on the leg (call flow, AI agent).
agent_number
string | null
The agent's phone or extension on an agent's leg; null on any leg with no person on it (the customer's leg, a call flow, an AI agent). CALL_CDR carries the agent's extension.
customer_number
string
The customer's number in E.164 format.
cli_number
string
Your CleverStack number: the number dialled on inbound, the caller ID on outbound.
recording_url
string | null
Present once recording has started. The full link is on CALL_COMPLETED and on CALL_CDR.
timestamp
string
When the event happened (UTC).
metadata
object
On calls started through the click-to-call API: the metadata you sent, returned unchanged on every lifecycle event.
On inbound calls CALL_INITIATED and CALL_RINGING fire when the first agent is rung, not when the customer's call arrives.
Click-to-call does not send CALL_RINGING.
An inbound call that never rings an agent sends only CALL_ANSWERED and CALL_COMPLETED for the customer, then CALL_CDR.
Inbound: CALL_ANSWERED (customer)
Your call flow answers the customer. No agent is on this leg yet.
One per call, a few seconds after it ends. It carries the lifecycle fields above, with participant: "call", plus the fields below. Read outcome to know how the call ended.
direction
Type: string
Meaning: inbound or outbound.
lifecycle_status
Type: string
Meaning: ended.
outcome
Type: string
Meaning: How the call ended: answered, missed, abandoned, no_answer, rejected, busy, failed, cancelled or voicemail.
status
Type: string
Meaning: Stays completed for older integrations. Read outcome instead.
Meaning: One entry per agent who was rung: who, times, durations, how their leg ended (outcome, is_connected) and hang-up codes. Each entry also carries org, user_email, extension_id, extension_uuid, agent_uuid, sip_call_id, read_codec, write_codec and call quality (mos, mos_min, jitter_ms_max, packet_loss_pct, poor_seconds, one_way_seconds); any of them is null when it was not measured or does not apply. Empty when no person was rung.
cdr_details.hangup_details
Type: object
Meaning: Telecom hang-up codes for the call, useful when a call fails.
Field
Type
Meaning
direction
string
inbound or outbound.
lifecycle_status
string
ended.
outcome
string
How the call ended: answered, missed, abandoned, no_answer, rejected, busy, failed, cancelled or voicemail.
status
string
Stays completed for older integrations. Read outcome instead.
One entry per agent who was rung: who, times, durations, how their leg ended (outcome, is_connected) and hang-up codes. Each entry also carries org, user_email, extension_id, extension_uuid, agent_uuid, sip_call_id, read_codec, write_codec and call quality (mos, mos_min, jitter_ms_max, packet_loss_pct, poor_seconds, one_way_seconds); any of them is null when it was not measured or does not apply. Empty when no person was rung.
cdr_details.hangup_details
object
Telecom hang-up codes for the call, useful when a call fails.
Sent when a call's recording is published, on inbound and outbound calls. revision goes up each time the recording changes: keep the highest. recording_url is set only when state is verified (playable); otherwise it is null.
event
Type: string
Meaning: CALL_RECORDING.
contract
Type: number
Meaning: Version of this body, currently 1.
org
Type: string
Meaning: Your organisation's number in CleverStack.
call_uuid
Type: string
Meaning: The call's id (join key).
revision
Type: number
Meaning: Goes up by one with every change to this call's recording.
state
Type: string
Meaning: verified when the recording is stored and recording_url works. Any other value (for example pending or lost) means there is no playable recording and recording_url is null.
recording_url
Type: string | null
Meaning: The recording link.
recording_seconds
Type: number | null
Meaning: Length of the recording in seconds.
Field
Type
Meaning
event
string
CALL_RECORDING.
contract
number
Version of this body, currently 1.
org
string
Your organisation's number in CleverStack.
call_uuid
string
The call's id (join key).
revision
number
Goes up by one with every change to this call's recording.
state
string
verified when the recording is stored and recording_url works. Any other value (for example pending or lost) means there is no playable recording and recording_url is null.
Sent when the call's transcript and analysis are ready, seconds to a minute after the call. For calls handled by people it needs the Post-call insights feature on your plan.
call_uuid, trace_id
Type: string
Meaning: The call's id (join key).
transcription_id
Type: number
Meaning: Id of this transcript.
status
Type: string
Meaning: completed, completed_no_speech, failed or failed_no_recording.
language_code
Type: string
Meaning: The detected language.
summary
Type: string
Meaning: A short summary of the call.
sentiment, sentiment_confidence
Type: string, number
Meaning: Overall sentiment and how sure the model is (0 to 1).
key_points, action_items
Type: string[]
Meaning: Lists of short sentences.
ai_suggested_disposition
Type: string | null
Meaning: The outcome the AI suggests. Not the saved disposition: that comes in DISPOSITION_SUBMITTED.
disposition
Type: string | null
Meaning: Older name for ai_suggested_disposition, same value.
segments[]
Type: array
Meaning: Transcript lines: speaker, start and end time in seconds, text, confidence and sentiment.
customer_number, agent_id, call_duration
Type: —
Meaning: Call context. agent_id is null on calls handled by an AI agent.
created_at, completed_at
Type: string
Meaning: When the transcription started and finished.
Field
Type
Meaning
call_uuid, trace_id
string
The call's id (join key).
transcription_id
number
Id of this transcript.
status
string
completed, completed_no_speech, failed or failed_no_recording.
language_code
string
The detected language.
summary
string
A short summary of the call.
sentiment, sentiment_confidence
string, number
Overall sentiment and how sure the model is (0 to 1).
key_points, action_items
string[]
Lists of short sentences.
ai_suggested_disposition
string | null
The outcome the AI suggests. Not the saved disposition: that comes in DISPOSITION_SUBMITTED.
disposition
string | null
Older name for ai_suggested_disposition, same value.
segments[]
array
Transcript lines: speaker, start and end time in seconds, text, confidence and sentiment.
customer_number, agent_id, call_duration
—
Call context. agent_id is null on calls handled by an AI agent.
created_at, completed_at
string
When the transcription started and finished.
Transcript of a call handled by an AI agent
{
"event": "TRANSCRIPTION_COMPLETED",
"call_uuid": "6b1f2c3d-0000-4000-8000-000000000003",
"trace_id": "6b1f2c3d-0000-4000-8000-000000000003",
"transcription_id": 30001,
"org": "1001",
"status": "completed",
"language_code": "en",
"transcription_duration_seconds": 95,
"error_message": null,
"summary": "Customer booked a cleaning appointment for Friday morning.",
"sentiment": "positive",
"sentiment_confidence": 0.9,
"key_points": [
"Wants Friday morning",
"Prefers the city centre branch"
],
"action_items": [
"Send booking confirmation"
],
"ai_suggested_disposition": "appointment_booked",
"disposition": "appointment_booked",
"created_at": "2026-11-19T13:02:10.000000Z",
"completed_at": "2026-11-19T13:02:20.000000Z",
"segments": [
{
"id": 1,
"speaker_tag": "SPEAKER_0",
"speaker_label": "agent",
"start_time": 0.4,
"end_time": 2.6,
"text": "Hello, how can I help you today?",
"confidence": 0.97,
"sentiment": "neutral",
"sentiment_confidence": 0.8
},
{
"id": 2,
"speaker_tag": "SPEAKER_1",
"speaker_label": "customer",
"start_time": 3,
"end_time": 5.8,
"text": "I'd like to book a cleaning for Friday morning.",
"confidence": 0.95,
"sentiment": "positive",
"sentiment_confidence": 0.8
}
],
"customer_number": "+919800000001",
"agent_id": null,
"call_duration": 95
}
Calls handled by an AI agent
An AI agent call needs no extra setup: subscribe to the call events above.
A call answered by an AI agent sends the same call events and fields as any other call.
agent_id and agent_number are null, and cdr_details.agents is empty, because no person took the call.
On an inbound AI call no agent is rung, so there is no CALL_INITIATED or CALL_RINGING: you receive CALL_ANSWERED and CALL_COMPLETED for the customer, then CALL_CDR.
TRANSCRIPTION_COMPLETED brings the transcript and the AI analysis, seconds to a minute after the call.
DISPOSITION_SUBMITTED with actor: "ai" brings the saved disposition, when auto-disposition is switched on.
Disposition events
The outcome saved for a call, by an agent, the AI or a campaign. Join it to the call events on call_uuid.
Saved disposition
DISPOSITION_SUBMITTED
Sent when a call's disposition is saved, changed or removed, on inbound, outbound and AI agent calls. On AI agent calls it is sent when auto-disposition is switched on.
call_uuid, trace_id, session_id
Type: string
Meaning: The call's id (join key). All three hold the same value.
disposition, sub_disposition
Type: string | null
Meaning: What was chosen.
code, label, sub_code, sub_label
Type: string | null
Meaning: The same choice as stored code and display label.
actor
Type: string
Meaning: Who saved it: agent, ai, campaign or system.
source
Type: string
Meaning: human or ai.
agent_user_id, agent_email
Type: string | null
Meaning: The agent, when a person saved it.
campaign_id
Type: number | null
Meaning: The campaign, when the call came from one.
record_id, table_code
Type: —
Meaning: The disposition record in CleverStack.
recorded_at
Type: string
Meaning: When it was saved.
deleted
Type: boolean
Meaning: true when the disposition was removed.
Field
Type
Meaning
call_uuid, trace_id, session_id
string
The call's id (join key). All three hold the same value.
disposition, sub_disposition
string | null
What was chosen.
code, label, sub_code, sub_label
string | null
The same choice as stored code and display label.
actor
string
Who saved it: agent, ai, campaign or system.
source
string
human or ai.
agent_user_id, agent_email
string | null
The agent, when a person saved it.
campaign_id
number | null
The campaign, when the call came from one.
record_id, table_code
—
The disposition record in CleverStack.
recorded_at
string
When it was saved.
deleted
boolean
true when the disposition was removed.
Saved by the AI
When an agent saves it, actor is agent, source is human, and agent_user_id and agent_email are filled.
Three groups in the picker: messages, the 24-hour session window, and message templates. WhatsApp events have the same flat shape as call events: event is the event name you subscribe to, trace_id joins the events of one message (it is the message id), customer_number is the customer and cli_number is your WhatsApp business number. Every key is always present.
Four events, sent for every conversation an AI agent handles, on calls and on WhatsApp. They have their own AI Agent Events group in the picker.
The four events
AI_CONVERSATION_STARTED
The AI answers the call or replies first on a chat
AI_ACTION_FAILED
A tool the AI uses fails, for example a call to your API returns an error
AI_HANDOFF
The AI transfers the customer to a person, before the person answers
AI_CONVERSATION_COMPLETED
The AI's part ends and its analysis is ready, a few seconds after; at most 60 seconds
Event
When it is sent
AI_CONVERSATION_STARTED
The AI answers the call or replies first on a chat
AI_ACTION_FAILED
A tool the AI uses fails, for example a call to your API returns an error
AI_HANDOFF
The AI transfers the customer to a person, before the person answers
AI_CONVERSATION_COMPLETED
The AI's part ends and its analysis is ready, a few seconds after; at most 60 seconds
All four carry org_uuid (your organisation id), call_uuid (join with the call events), run_id (one AI conversation) and metadata (what you sent when starting the call through click-to-call, unchanged; {} otherwise). Fields that do not apply are null, never missing.
On WhatsApp the four AI events have the same body, with channel: "whatsapp", conversation_id filled and call_uuid set to null. cli_number is your WhatsApp business number. AI_CONVERSATION_COMPLETED is sent when the AI closes the chat or the 24-hour window ends with no reply.