Troubleshoot missing or delayed webhooks

A webhook can appear missing because the event was not selected, the endpoint was unreachable, signature verification used a transformed body, the receiver returned a non-success response, or the application discarded a duplicate or out-of-order event incorrectly.

1. Reconcile the call first

If you know the call ID, read the authoritative stored state:

curl "https://callonline.app/v1/calls/call_opaque_identifier" \
  --header "Authorization: Bearer $CALLONLINE_API_KEY"

The ordered events array tells you whether CallOnline recorded the expected event. If it is not present there, the webhook subscription cannot deliver it.

2. Confirm the subscription

Call GET /v1/webhooks with a key that has callonline.webhooks. Verify:

• the URL is the intended environment and HTTPS route;
• the subscription is active;
• eventTypes contains the exact event string or *;
• the receiver is using the signing secret for that subscription.

dialed and call.answered are different event strings. Do not filter only on call-status values if you need carrier-oriented events.

3. Inspect receiver behavior

Check the receiver’s edge and application logs for the delivery ID and event header. Common causes are:

• a redirect to a login or trailing-slash URL;
• a firewall, allowlist, TLS, DNS, or timeout failure;
• reading parsed JSON before signature verification;
• comparing uppercase hex or omitting the sha256= prefix;
• returning 500 after durable acceptance, causing a repeat;
• returning 200 before durable acceptance, then losing the event.

Redact the secret, bearer keys, and sensitive body fields from logs.

4. Expect repeats and imperfect order

Use x-callonline-delivery as a unique key. A repeated delivery should return success after confirming the original was accepted. Do not require the previous lifecycle event to have arrived before accepting a newer one; network timing can differ.

When business state depends on order, compare the event with the current call record and its timestamps instead of trusting arrival order alone.

5. Replace a broken subscription safely

Create a new subscription and secret, deploy the new receiver configuration, verify a fixture delivery in a non-billable test, and then delete the old subscription. Do not expose a production secret in a manual replay tool.

CallOnline records failed attempts and a future retry time internally, but the public v1 contract does not promise an exact retry schedule. Build recovery around reconciliation, not a countdown.