Webhooks: call events delivered to your server

There are two webhook paths and they behave differently. Read the table before wiring anything:

An earlier version of this page described dotted event names, a 24-hour retry window, a failed-delivery queue, a replay screen and an event_id field. None of that exists. It was removed on 6 October 2026 after the delivery code was read line by line.

Agent webhooks

Setup

Set the webhook URL on the agent:

Copycurl -X PATCH https://api.call2me.app/v1/agents/agent_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"webhook_url": "https://your-server.com/webhooks/call2me"}'

Or in the dashboard: Agents → Edit → Webhooks.

Event types

Names use underscores. There is no separate transcript event — the transcript arrives inside call_ended, and the full turn-by-turn record is always available afterwards from GET /v1/calls/{call_id}.

Payload shape

Every agent event has the same three-key envelope; everything else is inside data:

Copy{
  "event": "call_ended",
  "timestamp": "2026-10-06T14:23:11.481Z",
  "data": {
    "call_id": "call_xyz789",
    "agent_id": "agent_abc123",
    "direction": "inbound",
    "from_number": "+905551234567",
    "to_number": "+908503030053",
    "duration_seconds": 134,
    "transcript": [ { "role": "agent", "text": "..." }, { "role": "user", "text": "..." } ],
    "recording_url": "https://…/calls/call_xyz789.ogg",
    "analysis": { "summary": "...", "sentiment": "positive" },
    "usage": { "llm_tokens": 1840, "stt_seconds": 75.4, "tts_chars": 570 }
  }
}

call_id and agent_id live inside data, not at the top level — an earlier version of this page put them on the envelope, which is not what is sent. timestamp is ISO-8601 UTC. Event-specific fields vary; treat anything beyond event, timestamp and data as absent.

Delivery: one attempt, no signature

The agent path is fire-and-forget. The platform POSTs once with a 10-second timeout; any response below 400 counts as delivered and anything else — including a timeout — is logged on our side and not retried. Your endpoint should therefore return 2xx fast and do its work asynchronously.

There is no signature header on agent webhooks. If you need to verify origin, use the account-level path below, or validate the call_id against GET /v1/calls/{call_id} before acting on it.

Deliveries are not guaranteed to be unique; if you retry on your side, dedupe on data.call_id + event.

Tenant-level webhooks (account events)

The events above are per-agent call events (set via PATCH /v1/agents/{id}). For account-level events — useful for headless and mobile integrations — register a single tenant webhook with your sk_ key:

Copycurl -X PUT https://api.call2me.app/v1/webhooks \
  -H "Authorization: Bearer sk_live_your_key" \
  -d '{"webhook_url": "https://your-app.com/hooks/call2me"}'
# → { "webhook_url": "...", "webhook_secret": "a1b2c3..." }   (store the secret)

Two events are delivered here:

voice_session.ended — a headless/AI voice session finished:

Copy{ "event": "voice_session.ended", "timestamp": "2026-07-07T10:00:00Z",
  "data": { "room_name": "agent_x_ab12", "agent_id": "agent_x",
            "external_user_id": "user_42", "duration_sec": 143.2,
            "cost_usd": 0.24, "ended_at": "2026-07-07T10:00:00Z" } }

wallet.low_balance — your balance dropped below the threshold (default $5), at most once per day:

Copy{ "event": "wallet.low_balance", "timestamp": "2026-07-07T10:00:00Z",
  "data": { "balance_usd": 3.10, "threshold_usd": 5.0 } }

These are the signed and retried deliveries: X-Call2Me-Signature: sha256=<hex HMAC-SHA256 of the raw body>, three attempts with 1 s, 2 s and 4 s pauses, and every attempt logged to webhook_deliveries with its status code. The secret is the one returned by PUT /v1/webhooks; store it, it is not shown again. Agent webhooks (above) do not get this — the two paths share only the {event, timestamp, data} envelope.

What's next

• Calls — the underlying call object webhooks reference
• Ephemeral tokens — mobile/headless integration tokens
• Post-Call Actions — declarative alternative to webhooks
• Errors & rate limits — what HTTP codes mean