Skip to main content
CallingBox emits signed webhooks at each stage of a call so your backend can react in real time instead of polling.

​
Three ways to subscribe

ModeWhen to use
Agent webhook_urlEvery call that agent handles (inbound or outbound) delivers to this URL. Set it on the agent once.
Per-call webhook_urlOverride for a single outbound call, decided at dispatch time.
Account endpointsOne or more stable endpoints that receive events for every call on the org.
All three modes share the same signed envelope, retry policy, and event catalog.

​
Agent-level inline webhook

Set webhook_url on the agent when you create or update it. Every call that agent handles emits events to that URL, signed with the organization’s default signing secret. 
{
  "name": "Appointment reminders",
  "type": "outbound",
  "webhook_url": "https://your-server.com/callingbox-webhook"
}

​
Per-call inline webhook override

Pass webhook_url on POST /v1/calls to override the agent’s default for a single call. 
{
  "agent_id": "agent-uuid-here",
  "to": "+15551234567",
  "webhook_url": "https://your-server.com/special-webhook"
}
You can fetch the default signing secret from the dashboard under Webhooks. Inline webhooks are ideal for small integrations and testing.

​
Account-wide endpoints

For production setups, register endpoints through POST /v1/webhook_endpoints and subscribe each endpoint to the events you care about. Every call on the org fans out to every matching endpoint.
cURL
curl https://api.callingbox.io/v1/webhook_endpoints \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-server.com/callingbox-webhook",
    "description": "Production CRM sync",
    "enabled_events": ["call.completed", "call.failed"]
  }'
The response includes the signing_secret one time only. Store it in your secrets manager before closing the response. Use enabled_events: ["*"] to subscribe to everything (default if you omit the field).

​
What CallingBox sends

CallingBox POSTs a JSON envelope to your URL. The body looks like this: 
{
  "id": "9c1d9f9e-21a1-4f6d-8fce-bf4a4b8a9e3f",
  "type": "call.completed",
  "created": 1713268800,
  "api_version": "2026-04",
  "data": {
    "call": {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "status": "completed",
      "result": { "confirmed": true },
      "duration_seconds": 34
    }
  }
}
Alongside the body you get these headers:
HeaderValue
Content-Typeapplication/json
CallingBox-Signaturet=<unix_ts>,v1=<hex_hmac>; see Security
CallingBox-Event-IdUUID unique to this delivery attempt. Use as an idempotency key.
CallingBox-Event-TypeSame as type in the body, for easy routing without parsing JSON.
X-CallingBox-EventLegacy alias of CallingBox-Event-Type.
X-CallingBox-Call-IdConvenience copy of data.call.id.

​
Respond fast

Your endpoint must return a 2xx within 10 seconds. Do the minimum amount of work necessary and enqueue the rest of the processing on your side. Any non-2xx response or timeout triggers a retry; see the retry policy.

​
Next steps

Event catalog

Every event type and its payload.

Security

Verify CallingBox-Signature.

Retries

Delivery schedule, idempotency, and replay.