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

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:

Open the Verbex Dashboard. Go to Webhooks.
Click Add Webhook and enter your HTTPS endpoint (domain URL).
Once the webhook endpoint is added, click on create webhook. That’s how the endpoint is registered in verbex.

Webhook Mode

When creating a new webhook, you can choose between two delivery modes — Push and Pull — depending on how you want to receive and manage event data.

Push Mode

Push mode automatically sends webhook events to a specified URL using HTTP requests. This allows external applications or systems to receive event notifications directly from Verbex. When Push mode is selected, configure the following fields:

Name: A descriptive name to identify the webhook, such as Payment Notifications.
Webhook URL: The HTTPS endpoint where webhook events will be delivered.
Workspaces: The workspaces associated with the webhook.
Agents: The agents whose events should be included.
Description: The purpose of the webhook and when it should be triggered.
Enable signed webhook: Attaches a cryptographic signature to each webhook payload, allowing the receiving system to verify that the event originated from Verbex.

Push mode is suitable for applications that require automatic event delivery to an external system.

Pull Mode

Pull mode stores webhook events on the Verbex platform, allowing users or external systems to retrieve them on demand instead of receiving automatic notifications. When Pull mode is selected, configure the following fields:

Name: A descriptive name to identify the webhook.
Workspaces: The workspaces associated with the webhook.
Agents: The agents whose events should be stored.
Description: The purpose of the stored events and how they will be used.

Unlike Push mode, Pull mode does not require a Webhook URL because events are stored for later retrieval rather than automatically delivered to an external endpoint. Pull mode is suitable for applications that prefer to retrieve and process event data when needed.

Creating a Webhook

Open the Create new webhook window and select the preferred delivery mode.
Complete the required fields and configure the relevant workspaces and agents.
Click Create to save the webhook configuration.

Fields marked with a red asterisk (*) are mandatory. To exit without creating a webhook, click Cancel or the X icon in the upper-right corner of the window.

Difference Between Push and Pull Modes

Feature	Push Mode	Pull Mode
Event delivery	Automatically sends events over HTTP	Stores events for retrieval on demand
Webhook URL	Required	Not required
Event retrieval	Events are delivered to the configured endpoint	Events are fetched when needed
Signed webhook	Available	Not shown
Best suited for	Automatic notifications and system integrations	On-demand event retrieval and processing

Select the delivery mode that best matches your application’s integration requirements and preferred method of handling webhook events.

Webhook Data Format

Call Started Event

{
"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

{
"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

{
"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.

{
  "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)

Getting Started

Build Your AI Agent - Step by Step

Navigating within Verbex

Batch Call

Monitor Your AI Agent

Register & Handle Webhooks

Resources

Role Based Access Control

Web Application Firewall

KMS Encryption

Verbex Webhook Implementation Guide

What You Get (Benefits)

When to Use Webhooks

Event Catalogue & Typical Client Actions

Endpoint Settings

Basic Requirements

Request Format

How to Configure Webhook in Verbex:

Webhook Mode

Push Mode

Pull Mode

Creating a Webhook

Difference Between Push and Pull Modes

Webhook Data Format

Call Started Event

Call Ended Event

PCA Completed Event

Call Transfer Event

Call Transfer Event Field Descriptions

Implementation Notes

Call Transfer Event Implementation Notes

Field Descriptions

​What You Get (Benefits)

​When to Use Webhooks

​Event Catalogue & Typical Client Actions

​Endpoint Settings

​Basic Requirements

​Request Format

​How to Configure Webhook in Verbex:

​Webhook Mode

​Push Mode

​Pull Mode

​Creating a Webhook

​Difference Between Push and Pull Modes

​Webhook Data Format

​Call Started Event

​Call Ended Event

​PCA Completed Event

​Call Transfer Event

​Call Transfer Event Field Descriptions

​Implementation Notes

​Call Transfer Event Implementation Notes

​Field Descriptions

What You Get (Benefits)

When to Use Webhooks

Event Catalogue & Typical Client Actions

Endpoint Settings

Basic Requirements

Request Format

How to Configure Webhook in Verbex:

Webhook Mode

Push Mode

Pull Mode

Creating a Webhook

Difference Between Push and Pull Modes

Webhook Data Format

Call Started Event

Call Ended Event

PCA Completed Event

Call Transfer Event

Call Transfer Event Field Descriptions

Implementation Notes

Call Transfer Event Implementation Notes

Field Descriptions