Replay and troubleshoot webhook deliveries

Webhook deliveries can fail for many reasons — a redeploy, a draining load balancer, a half-finished signing-secret rotation. The console keeps a record of every delivery so you can inspect and redrive.

Find a failed delivery

Open Developers → Webhooks and click into the subscription. The detail page lists every attempt with its status, attempt count, and timestamp. The subscription list shows the last successful and last unsuccessful delivery time per endpoint.

If a subscription is inside the seven-day signing-secret rotation window, the list shows a Rotating badge — see Verify webhook signatures.

Read the delivery detail

Every delivery row carries:

• The event type (for example kyc.session.completed).
• The timestamp the event was emitted.
• The number of delivery attempts so far.
• The most recent HTTP status the receiver returned, or a transport-level error.

Use the receiver’s HTTP status to decide whether the failure is in your code (4xx) or in the network path (5xx, connection reset, timeout).

Replay the delivery

Open the failed delivery and click Replay. The platform re-signs the payload with the current signing secret and POSTs again. A replay does not create a new event — it reuses the original X-Webhook-Id — but it does create a new delivery with its own X-Webhook-Delivery-Id and X-Webhook-Origin: replay. That lets your receiver tell a deliberate replay from the original while still deduping on the stable event id.

Common failure modes

• 401 / 403 from your receiver — the signature did not verify. Read the raw body before any JSON middleware reshapes it, and constant-time-compare. See Verify webhook signatures.
• 404 from your receiver — the URL has moved. Open the subscription, click Edit, and update the URL.
• Connection timeouts or TLS errors — your endpoint is unreachable. Check DNS, certificate, and firewall.
• Replays signed with a different secret than the original — you are inside a rotation window. Accept both secrets for the full seven days.

Auto-disabled endpoints

If an endpoint fails for a sustained streak of deliveries, the platform automatically disables the subscription to stop sending to a dead endpoint, and notifies your organization’s owners and admins. A disabled subscription shows a banner on its detail page. Once your endpoint is healthy again, click Re-enable — it resumes deliveries and keeps your existing signing secret (no rotation needed). Re-enabling does not replay the deliveries that were skipped while disabled; replay those individually if you need them.

When deliveries stop

1. Confirm the subscription is still active — check for the auto-disabled banner above and re-enable if needed.
2. Confirm you are looking at the right mode — test and live are isolated. See Modes and regions.
3. Confirm at least one subscribed event has happened in that mode. Note that only kyc.session.completed, kyc.session.cancelled, and kyc.session.manual_review_requested produce deliveries — see Create a webhook endpoint.
4. Check the last unsuccessful delivery time on the subscription detail page.

If the receiver is healthy but deliveries are not arriving, see Why is my webhook not firing?.