> ## Documentation Index > Fetch the complete documentation index at: https://docs.verbex.ai/llms.txt > Use this file to discover all available pages before exploring further. # Verbex Webhook Implementation Guide Webhooks let your systems get real-time notifications from Verbex about call lifecycle and PCA availability. As events occur, Verbex sends POST requests with JSON payloads to your HTTPS endpoint so you can update CRMs, trigger workflows, and fetch PCA immediately.\ \ Verbex sends real-time webhooks at Multiple key moments in a call’s lifecycle: * **Call Started** ( `CallHandler.CallStarted` ) * **Call Ended** ( `CallHandler.CallEnded` ) * **Call Transfer** ( `CallHandler.CallTransferred` ) * **PCA Completed** ( `callAnalysis.pcaCompleted` , typically 1–30s after end) These events let your systems react instantly—create or update CRM cases, trigger alerts, and (most importantly) **fetch PCA** to automate next steps such as follow-up outbound calls, notifications, or escalations. ## **What You Get (Benefits)**  * **Instant awareness** of live calls and completion (no polling). * **Actionable insights** the moment PCA is ready. * **Automated workflows**: kick off follow-ups, send SMS/email, open tickets, or route to a human agent using PCA outcomes. * **Operational visibility**: power real-time dashboards for call status and PCA readiness. ## **When to Use Webhooks** Use these webhooks if you need to: * **Show live call status** in CRM/Helpdesk/BI dashboards. * **Automate post-call actions** the moment PCA is available. * **Orchestrate follow-ups** (e.g., schedule/trigger another outbound call). * **Sync data** to external systems (CRM, ticketing, data warehouse) tied to `call_id`. ## **Event Catalogue & Typical Client Actions** | **Event** | **Purpose** | **Typical Client Action** | | :-------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------ | :----------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Call Started** (`CallHandler.CallStarted`) | Signals a new call session has begun. | Create/attach a live engagement record; mark status = “In Progress”. | | **Call Ended** (`CallHandler.CallEnded`) | Signals call completion. | Mark record “Completed”; prepare to await PCA. | | **PCA Completed** (`callAnalysis.pcaCompleted`) | PCA is ready (1–30s post-end). | **Fetch PCA by**`call_id`; evaluate rules; trigger follow-ups/notifications/escalations. | | **Call Transfer** ( `CallHandler.CallTransferred` ) | Signals a call transfer has been initiated. Triggered when the AI agent transfers the call to a human agent or external number. | Route call to receiving agent using transfer\_to destination; update CRM record with `transfer status` and `reason`; send `context/transcript` to receiving agent. | **Note:** Events can arrive out of order due to network conditions. Use `traceId` to deduplicate; treat `call_id` as the stable identity for your records. ## **Endpoint Settings** ### **Basic Requirements** * **HTTP Method**: POST * **Protocol**: HTTPS (required) * **Domain**: Custom domain (required; IP addresses not allowed) * **Content-Type**: application/json ### **Request Format** ```text theme={null} POST /your-webhook-endpoint HTTP/1.1 Content-Type: application/json User-Agent: ReactorNetty/1.1.13 X-Webhook-Event: CallHandler.CallEnded X-Webhook-Traceid: 94c950a0-1694-4b7c-9891-9364c261e4e1 X-Webhook-Timestamp: 2025-11-10T01:01:14.552985018Z ``` **Custom Headers:** * `X-Webhook-Event`: Event name (e.g., `CallHandler.CallEnded`) * `X-Webhook-Traceid`: Webhook unique identifier (same as `traceId` in the body) * `X-Webhook-Timestamp`: Timestamp in ISO 8601 format ## How to Configure Webhook in Verbex: 1. Open the Verbex **Dashboard**. Go to **Webhooks**. Hook1 Pn 2. Click **Add Webhook** and enter your HTTPS endpoint (domain URL). Hook2 Pn 3. Once the webhook endpoint is added, click on create webhook. That's how the endpoint is registered in verbex. ## **Webhook Data Format** ### **Call Started Event** ```json theme={null} { "traceId": "69ef5c43425e3c729ab8c83f", "organizationId": "27117463-c11e-4c75-affd-f743216f1bef", "payload": { "call_id": "69ef7c43425e3c729ab8c83f", "status": "success", "agent_id": "c51aa1b1-7eac-452d-8ba5-86a922d694e7" }, "eventName": "CallHandler.CallStarted", "event": "CallStarted", "timestamp": "2026-04-27T12:53:25.241195387Z" } ``` ### **Call Ended Event** ```json theme={null} { "traceId": "69ef5c43425e3c729ab8c83f", "organizationId": "27117463-c11e-4c75-affd-f743216f1bef", "payload": { "call_id": "62ef5c43425e3c729ab8c83f", "status": "success", "agent_id": "c31ab1b1-7eac-452d-8ba5-86a922d694e7" }, "eventName": "CallHandler.CallEnded", "event": "CallEnded", "timestamp": "2026-04-27T12:56:41.599271364Z" } ``` ### **PCA Completed Event** ```json theme={null} { "traceId": "69ef5c43425e3c729ab8c83f", "organizationId": "27117463-c11e-4c75-affd-f743216f1bef", "payload": { "reason": "success", "agent_id": "c51ab1b1-7eac-452d-8ba5-86a922d694e7", "call_id": "69ef5c43425e3c729ab8c83f", "status": "success", "timestamp": 1777294619200 }, "eventName": "callAnalysis.pcaCompleted", "event": "pcaCompleted", "timestamp": "2026-04-27T12:56:59.342041497Z" } ``` ### **Call Transfer Event** The Call Transfer event is triggered when the AI agent initiates a transfer of the call to a human agent or external destination. This event provides comprehensive details about the transfer attempt, including the transfer destination, call summary, and transcript. ```json theme={null} { "call_id": "697a020fc0baee039d0013b4", "agent_id": "d077dc85-ee45-48cd-ac65-fd49df53cdba", "status": "failed", "transfer_to": "sip:01751373839@115.127.146.155", "caller": { "phone_number": "+8801762668080" }, "call_summary": { "duration_seconds": 45.621591, "topics_discussed": [ "call_transfer_request" ], "actions_taken": [ "Acknowledged transfer request", "Initiated call transfer to human agent" ], "transfer_reason": "Customer requested to speak with a human agent.", "customer_sentiment": "neutral", "unresolved_issues": [] }, "transcript": [ { "role": "user", "content": "Hi, I need assistance with my account." }, { "role": "agent", "content": "How can I help you today?" }, { "role": "user", "content": "Okay. Can you transfer the call to a human agent?" }, { "role": "agent", "content": "Of course, I'll transfer you to a human agent now. Please hold on a moment." }, { "role": "agent", "content": "Please wait while we connect you to a human agent." } ], "metadata": { "call_start_time": "2026-01-28T12:33:37.475817+00:00", "call_end_time": "2026-01-28T12:34:23.097263+00:00", "language": "en-US" } } ``` ### Call Transfer Event Field Descriptions | Field | Type | Description | | :-------------------------------- | :----- | :----------------------------------------------------------------------------------------------------------------------------------------- | | `call_id` | string | Unique identifier for the call. Used as a stable identifier for your records. | | `agent_id` | string | Unique identifier for the AI agent handling the call. | | `status` | string | Transfer status. Values: `pending`, `initiated`, `success`, `failed`. Indicates whether the transfer was successfully completed or failed. | | `transfer_to` | string | Destination of the transfer. Can be a SIP address, phone number, or internal extension. | | `caller.phone_number` | string | Phone number of the caller initiating the call. | | `call_summary.duration_seconds` | number | Total duration of the call in seconds before transfer was initiated. | | `call_summary.topics_discussed` | array | List of topics discussed during the call. | | `call_summary.actions_taken` | array | List of actions performed by the AI agent during the call. | | `call_summary.transfer_reason` | string | Reason provided for initiating the transfer. | | `call_summary.customer_sentiment` | string | Overall sentiment of the customer. Values: `positive`, `neutral`, `negative`. | | `call_summary.unresolved_issues` | array | List of issues not resolved before transfer. | | `transcript` | array | Complete transcript of the call conversation. | | `transcript[].role` | string | Speaker in the transcript. Values: `user` or `agent`. | | `transcript[].content` | string | Content of the message spoken. | | `metadata.call_start_time` | string | ISO 8601 timestamp of when the call started. | | `metadata.call_end_time` | string | ISO 8601 timestamp of when the call ended or transfer was initiated. | | `metadata.language` | string | Language code of the call (e.g., "en-US"). | ## **Implementation Notes** **Important**: The webhook payload structure may change without notice. On the receiving side, please note the following: * It is recommended to store the entire payload received as JSON data. * Consider the possibility that new fields may be added. * Implement it so that unknown fields do not cause errors. ### **Call Transfer Event Implementation Notes** **Transfer Status Tracking:** Monitor the `status` field to determine if a transfer was successful. Failed transfers may require fallback handling or alerting. **Transfer Destination Validation:** Validate the `transfer_to` field format before routing. Ensure it matches your system's expected destination format (SIP URI, phone number, etc.). **Preserve Call Context:** Use `call_id` as the primary identifier to correlate this event with the original Call Started event for complete call lifecycle tracking. **Customer Sentiment Analysis:** Consider the `customer_sentiment` field when prioritizing transfers or determining escalation urgency. **Unresolved Issues:** Review the `unresolved_issues` array to ensure the receiving agent has context about what was not resolved. **Transcript Availability:** The complete `transcript` is included to help the receiving agent understand the conversation history and customer needs. **Typical Client Actions:** * Route call to the receiving agent using the `transfer_to` destination * Update CRM record with transfer status, reason, and customer sentiment * Send complete transcript and unresolved issues to the receiving agent * Track transfer success rates for quality assurance * Log transfer reason and customer sentiment for analytics ## **Field Descriptions** | **Field** | **Type** | **Description** | | :------------------ | :------- | :------------------------------------------------- | | `organizationId` | string | Organization ID | | `traceId` | string | Webhook unique identifier (used for deduplication) | | `eventName` | string | Event type | | `timestamp` | number | UNIX timestamp (seconds) | | `payload.call_id` | string | Call ID | | `payload.agent_id` | string | AI agent ID | | `payload.status` | string | Status | | `payload.reason` | string | Reason (PCA only) | | `payload.timestamp` | number | UNIX timestamp (milliseconds, PCA only) |