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.

​
Two ways to subscribe

ModeWhen to use
Per-call webhook_urlYou want events for a single call, decided at the moment you create it.
Account endpointsYou want one or more stable endpoints that receive events for every call on the org.
Both modes share the same signed envelope, retry policy, and event catalog.

​
Per-call inline webhook

Set webhook_url when creating a call. That URL receives every lifecycle event for that call, signed with the organization’s default signing secret. 
{
  "to": "+15551234567",
  "prompt": "Confirm appointment tomorrow at 2pm",
  "returns": { "confirmed": "boolean" },
  "webhook_url": "https://your-server.com/callingbox-webhook"
}
You can fetch the default signing secret from the dashboard under Webhooks. Inline webhooks are ideal for one-off integrations or 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 — 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.