> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bey.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhook Events

> Receive real-time events for calls with managed agents

Configure webhooks to receive real-time events from agent calls.
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 call 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 call 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
```

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

## Configuration

Webhooks are configured through the dashboard:

1. Navigate to [Your Settings](https://app.bey.chat/settings) → Webhooks Tab
2. Enter your webhook endpoint URL
3. Save to trigger a test event for validation

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

```json theme={null}
{
  "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.

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

### Message Events

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

```json theme={null}
{
  "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"
  }
}
```

<Tip>
  The agent's greeting message marks the start of a call and can be used to trigger call initialization logic in your webhook handler.
</Tip>

### Call Ended Events

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

```json theme={null}
{
  "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](https://github.com/bey-dev/bey-examples/tree/main/call-events-webhook#readme) for full implementation including event handling, CORS configuration, and deployment scripts.

## Next Steps

<CardGroup cols={2}>
  <Card title="Webhook Processor Example" icon="github" href="https://github.com/bey-dev/bey-examples/tree/main/call-events-webhook#readme">
    Complete implementation with deployment scripts
  </Card>

  <Card title="Back to Managed Agents" icon="arrow-left" href="/integrations/managed-agents">
    Return to managed agents overview
  </Card>
</CardGroup>