--- title: VoiceBot Webhooks slug: intelligent-voice-agents/voicebot-webhooks docTags: createdAt: 2026-01-09T13:36:15.941Z --- 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** :::BlockQuote 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. :::BlockQuote \{ "session\_id": "\", "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": "\", "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 :::BlockQuote \{ "event\_type": "sentiment | summary | intent | entity | outcome | transcript", "event\_id": "\", "event\_data": \{} } ::: ## Transcript Event Data :::BlockQuote \{ "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) :::BlockQuote \{ "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) :::BlockQuote \{ "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) :::BlockQuote \{ "http\_code": 200, "response": \{ "data": \{} } } ::: ## Transcript Events Webhook ### When Triggered on: - turn-progress - turn-complete ### Expected Response (2xx) :::BlockQuote \{ "http\_code": 200, "response": \{ "data": \{} } } ::: ## Error Response (All Webhooks) :::BlockQuote \{ "http\_code": 500, "response": \{ "data": null, "error\_data": \{ "error\_code": "CL52894", "message": "Internal server error", "description": "Internal server error" } } } :::