VoiceBot Webhooks
16 min
VoiceBot Webhooks allow you to receive real-time notifications about events occurring during a voicebot call. When specific events occur, the VoiceBot platform sends HTTP POST requests to your configured webhook endpoints.
Webhooks enable:
- Real-time transcripts
- Dynamic webhook overrides per session
- Agent transfer orchestration
- Post-call analytics pipelines
Overview
Webhooks can be:
- Configured at bot creation time
- Overridden per session using:
- Custom parameters on the voicebot WebSocket connection
- The response of the Session Start webhook
Webhook overrides (except session start) are cached for the lifecycle of the session.
Supported Webhook Types
Webhook | Description |
|---|---|
session_start | Triggered when a voicebot call begins |
session_end | Triggered when the conversation ends |
pre_agent_transfer | Triggered before transferring to a human agent |
transcript_events | Triggered on turn-progress and turn-complete |
Important Notes
- Timeouts: Your webhook must respond within the configured timeout
- Success Criteria: HTTP 2xx responses are treated as successful
- Retries: Failed webhooks are retried based on the retry configuration
- Ordering: Consumers must handle out-of-order events
- Session Scope: Webhook overrides apply only to a single session
- Bot-to-Bot Transfer: Webhook endpoints should be generic
- Special Override: call-setup-url custom param overrides the session_start webhook
Common Webhook Request Format
All webhook requests follow the same structure.
{
"session_id": "<voicebot session id>",
"conversation_id": "<voicebot conversation id>",
"start_time": "2025-07-16T11:40:57.000Z",
"end_time": null,
"landing_number": "",
"external_id": "CAxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"session_state": "session_start | session_in_progress | session_end",
"trigger_reason": "timer | turn-complete | turn-progress | pre-agent-transfer | start | end",
"contact_uri": "<phone number / endpoint>",
"network_type": "sip | pstn",
"account_id": "",
"bot_id": "bot_uuid",
"bot_name": "bot_name",
"metadata": {
"call_sid": "CAxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"stream_sid": ""
},
"custom_parameters": {
"key1": "value1",
"key2": "value2"
},
"events": [
{
"event_type": "sentiment",
"event_id": "evt_1",
"event_data": {}
}
]
}
Event Object
{
"event_type": "sentiment | summary | intent | entity | outcome | transcript",
"event_id": "<event id>",
"event_data": {}
}
Transcript Event Data
{
"transcripts": [
{
"sequence": 1,
"status": "inprogress | completed",
"transcript_segments": [
{
"speaker": "assistant",
"text": "Hello! How may I help you?",
"start_timestamp": "2025-10-31T21:27:44.330756Z",
"end_timestamp": "2025-10-31T21:27:51.082429Z"
}
]
}
]
}
Transcript Notes
- status defaults to completed
- inprogress is used only for active turns
- Accumulated transcripts are sent per turn
- At most one sequence per webhook
- Transcripts are not sent in session_end webhook
Webhook Types
Session Start Webhook
When
Triggered when a voicebot call begins.
Allows dynamic override of other webhook endpoints.
Expected Response (2xx)
{
"http_code": 200,
"response": {
"data": {
"greeting_message": {
"text": "Dynamic greeting message for the user"
},
"session_constants": {
"phone_number": "x_call_from"
},
"conversation_assistant_id": "",
"webhook_config": {
"session_end": {
"url": "https://api.example.com/webhooks/session-end"
},
"pre_agent_transfer": {
"url": "https://api.example.com/webhooks/pre-agent-transfer"
},
"insights_events": {
"url": "https://api.example.com/webhooks/insights",
"trigger_type": "timer",
"trigger_interval_sec": 30
},
"transcript_events": {
"url": "https://api.example.com/webhooks/transcripts"
}
}
}
}
}
Pre-Agent Transfer Webhook
When
Triggered when the bot detects user intent to talk to an agent.
Expected Response (2xx)
{
"http_code": 200,
"response": {
"data": {
"agent_transfer_message": {
"text": "Connecting you to a support agent"
}
}
}
}
Session End Webhook
When
Triggered when the conversation ends.
Expected Response (2xx)
{
"http_code": 200,
"response": {
"data": {}
}
}
Transcript Events Webhook
When
Triggered on:
- turn-progress
- turn-complete
Expected Response (2xx)
{
"http_code": 200,
"response": {
"data": {}
}
}
Error Response (All Webhooks)
{
"http_code": 500,
"response": {
"data": null,
"error_data": {
"error_code": "CL52894",
"message": "Internal server error",
"description": "Internal server error"
}
}
}