Receive call-status webhooks

Webhook subscriptions belong to the authenticated account. A subscription contains a destination URL, an event-type filter, an active status, and a signing secret used to authenticate deliveries.

Create a subscription

curl https://callonline.app/v1/webhooks \
  --request POST \
  --header "Authorization: Bearer $CALLONLINE_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "url": "https://example.com/webhooks/callonline",
    "eventTypes": ["dialed", "call.answered", "call.ended", "dial_failed"]
  }'

eventTypes must contain at least one non-empty string. Use "*" to receive all product and carrier-oriented call events. A successful create returns HTTP 201 with id, url, eventTypes, status, signingSecret, and createdAt.

Store signingSecret in a server-side secret manager. You can provide a secret of at least 16 characters when creating the subscription, or let CallOnline generate one.

Delivery shape

Each delivery is an HTTP POST with JSON similar to:

{
  "id": "delivery-uuid",
  "type": "call.answered",
  "callId": "call-uuid",
  "createdAt": "2026-07-14T14:30:08.000Z",
  "data": {},
  "call": {
    "to": "+19045550101",
    "from": "+19045550100",
    "status": "answered",
    "objective": "Qualify this lead and schedule an estimate.",
    "onBehalfOf": "Acme Services",
    "metadata": {
      "workflowId": "lead-interceptor",
      "deploymentId": "deployment-acme"
    }
  }
}

data contains the event-specific payload. call carries stable call context and the metadata supplied to POST /v1/calls, so receivers can correlate lifecycle events with the originating workflow without querying CallOnline first.

The request includes:

Header	Purpose
x-callonline-delivery	Unique delivery identifier for deduplication
x-callonline-event	Event type used by the subscription filter
x-callonline-signature	sha256= plus the lowercase HMAC-SHA256 digest of the raw body
content-type	application/json

Acknowledge after durable acceptance

The receiver should perform a small, reliable sequence:

1. Read the raw request bytes without transforming them.
2. Verify the signature before parsing or trusting fields.
3. Check whether x-callonline-delivery was already accepted.
4. Store the event or enqueue it transactionally.
5. Return a 2xx response quickly.
6. Process slower business logic asynchronously.

Any non-success response is treated as a failed delivery. Your endpoint should not return success before it can recover the accepted event after a crash.

List or delete subscriptions

List active and non-deleted subscriptions with GET /v1/webhooks. Delete one with DELETE /v1/webhooks/{webhookId}. Deletion returns the numeric ID and status: "deleted".

For recovery, reconcile important call IDs with GET /v1/calls/{callId}. A webhook is a notification channel, not the only authoritative way to inspect the stored call.