Webhooks & events

Calleague can tell your own systems what's happening as calls play out. Instead of constantly asking the REST API "is it done yet?", you subscribe to call-lifecycle events and get a message the moment a call starts, connects, finishes, or a recording or transcript becomes available. This page covers how to register a webhook, the events you can receive, the payload shape, verification, and retries.

At a glance

How it works

A webhook is a web address your service hosts. You register that address with Calleague and pick the events you care about; Calleague then sends a JSON POST to it whenever a matching event fires.

curl -s -X POST https://app.calleague.ai/api/core/webhook \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "url": "https://your-app.example.com/hooks/calleague",
        "events": ["call.started", "call.completed", "recording.ready"]
      }'

Every delivery carries your API key, so you can confirm it really came from Calleague:

Authorization: Bearer $TOKEN

Events you can receive

Example payload

When a subscribed event fires, Calleague sends JSON to your endpoint:

{
  "event": "call.completed",
  "deliveryId": "dl_4c19",
  "occurredAt": "2026-01-01T12:01:24.000Z",
  "data": {
    "callId": "cl_8f2a",
    "agentId": "ag_123",
    "direction": "inbound",
    "durationSec": 84,
    "endedReason": "completed",
    "language": "tr",
    "metadata": { "orderId": "A-1042" }
  }
}

The metadata you passed when starting the call is echoed back here, so you can match the event to your own record without a second lookup.

Reply fast — your endpoint should acknowledge before doing slow work:

HTTP/1.1 200 OK

Verification

Retries & reliability

If your endpoint doesn't reply 2xx (it errors, times out, or is unreachable), Calleague retries the delivery with a growing wait for a limited window. To stay correct under retries:

• Be repeatable. Key your processing on deliveryId (or callId + event) and treat a repeat as a no-op.
• Acknowledge first, work later. Reply 2xx straight away, then queue the slow work.
• Don't block. A slow handler causes timeouts, which trigger more retries.
• Tolerate out-of-order delivery. A retry of an earlier event can land after a later one.

If something looks different

Webhooks vs. REST

FAQ

Next steps