Webhooks: real-time call events to your endpoint

Webhooks are the way to react to call events without polling. The platform posts JSON to your URL, you do the work, you reply with 2xx.

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

Payload shape

Every event has the same envelope:

Copy{
  "type": "call.ended",
  "call_id": "call_xyz789",
  "agent_id": "agent_abc123",
  "timestamp": "2026-05-06T14:23:11Z",
  "data": {
    "duration_ms": 134000,
    "status": "completed",
    "transcript_url": "https://api.call2me.app/v1/calls/call_xyz789/transcript",
    "recording_url": "https://api.call2me.app/v1/calls/call_xyz789/recording.mp3"
  }
}

Event-specific fields go inside data. The envelope (type, call_id, agent_id, timestamp) is stable.

Verifying the signature

Each request carries X-Call2Me-Signature: sha256=<hex>. Compute the expected signature on the raw body using your webhook secret (visible in the dashboard once at create time):

Copyimport hmac, hashlib

def verify(body: bytes, header: str, secret: str) -> bool:
    expected = hmac.new(secret.encode(), body, hashlib.sha256).hexdigest()
    received = header.replace("sha256=", "")
    return hmac.compare_digest(expected, received)

Always use a constant-time comparison (hmac.compare_digest in Python, crypto.timingSafeEqual in Node).

Retry behavior

If your endpoint returns 5xx or times out (>10s), the platform retries with exponential backoff:

• 1m, 5m, 30m, 2h, 6h, 24h

After 24h of failures the event lands in the dead-letter queue. You can view and replay from Settings → Webhooks → Failed.

4xx responses are NOT retried — they signal a permanent rejection.

Idempotency

Each event has a stable event_id field. Webhooks may be delivered more than once (rare, but possible during retries that succeeded after a network blip). Dedupe on event_id:

Copyif not redis.set(f"event:{event_id}", "1", nx=True, ex=86400):
    return  # already processed

What's next

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