Webhooks & events
Subscribe to Calleague call-lifecycle events and react in real time, with an example payload.
Calleague can notify your own systems as calls happen. Instead of polling the API, you subscribe to call-lifecycle events and react the moment a call is placed, connects, or ends. This page shows how to subscribe and what an event payload looks like.
Subscribing
You register a callback URL — a webhook endpoint your service hosts — from the integrations area of the app, and choose which events you want delivered. Calleague then POSTs a JSON payload to that URL each time a matching event occurs. Requests carry your API key as a Bearer token so you can verify they came from Calleague.
Authorization: Bearer <YOUR_API_KEY>Events you can receive
| Event | Fires when |
|---|---|
call.started | A call is placed or received. |
call.connected | The call connects and audio begins. |
call.ended | The call finishes, with its duration. |
Example payload
When a subscribed event fires, Calleague POSTs JSON to your endpoint:
{
"event": "call.ended",
"data": {
"callId": "<call-id>",
"assistantId": "<assistant-id>",
"direction": "inbound",
"durationSec": 42,
"endedAt": "2026-01-01T12:00:42.000Z"
}
}Your endpoint should respond quickly with a 2xx status to acknowledge receipt, then do any slower work asynchronously.
The event names and payload fields above are illustrative — treat them as the shape of the integration, not a fixed contract. Build against the events your account actually delivers, and ignore fields you do not recognise so new ones can be added safely.
Choosing the right pattern
| You want to… | Use |
|---|---|
| React the moment a call event happens | A webhook subscription |
| Read past calls or assistants on demand | The REST API |
Make your handler idempotent. A webhook may occasionally be delivered more than once, so key your processing on callId + event and treat a repeat as a no-op.