Webhook Events

Configure webhooks to receive real-time events from agent conversations. Process conversations as they happen in your own systems.

Use Cases

Webhook events are ideal for:

Real-time monitoring: Track conversations and agent performance as they happen
System integration: Sync conversation data with CRMs, analytics platforms, or internal tools
Automated workflows: Trigger actions based on conversation events or sentiment analysis
Custom analytics: Build custom dashboards and reporting on top of conversation data

Requirements

Your webhook endpoint must:

Be publicly accessible from the internet
Accept POST requests with JSON payloads
Return a 200 status code to acknowledge receipt

The endpoint should also support the following CORS headers:

Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: POST
Access-Control-Allow-Headers: Content-Type

CORS headers are required because webhook validation currently happens in the browser. This requirement will be removed in a future release.

Configuration

Webhooks are configured through the Studio:

Navigate to Your Settings → Webhooks Tab
Enter your webhook endpoint URL
Save to trigger a test event for validation

When you save your webhook URL, a test event will be sent to validate your endpoint:

{
  "event_type": "test"
}

Your endpoint must return a 200 status code to confirm it’s working correctly.

Event Types

Your webhook endpoint will receive POST requests with different event types.

We currently do not support retry logic for failed webhook deliveries. Ensure your endpoint is reliable to avoid missing events.

Message Events

Triggered whenever a message is sent during a conversation (by either the user or agent).

{
  "event_type": "message",
  "call_id": "call_abc123",
  "message": {
    "sender": "user",  // or "agent"
    "message": "Hello, I need help with my order",
    "sent_at": "2024-01-15T10:30:45.123Z"
  },
  "call_data": {
    "userName": "John Doe",
    "agentId": "agent_xyz789"
  }
}

The agent’s greeting message marks the start of a conversation and can be used to trigger conversation initialization logic in your webhook handler.

Call Ended Events

Triggered when a conversation concludes, includes full transcript and evaluation.

{
  "event_type": "call_ended",
  "call_id": "call_abc123",
  "user_name": "John Doe",
  "evaluation": {
    "topic": "Order status inquiry",
    "user_sentiment": "positive",  // or "neutral", "negative"
    "duration_minutes": 3.5,
    "messages_count": 12
  },
  "messages": [
    {
      "sender": "agent",
      "message": "Hello, how may I help you today?",
      "sent_at": "2024-01-15T10:30:30.123Z"
    },
    // ...
  ]
}

Complete Example

See our webhook processor example for full implementation including event handling, CORS configuration, and deployment scripts:

Webhook Processor Example

Complete implementation with deployment scripts

Get Started

Core Concepts

Integrations

Production Guides

Learn More

Use Cases

Requirements

Configuration

Event Types

Message Events

Call Ended Events

Complete Example

Webhook Processor Example

​Use Cases

​Requirements

​Configuration

​Event Types

​Message Events

​Call Ended Events

​Complete Example

Webhook Processor Example

Use Cases

Requirements

Configuration

Event Types

Message Events

Call Ended Events

Complete Example