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.

For seven days after a signing-secret rotation, the list shows a Rotating badge. The badge is a reminder to finish the cutover on your side; it does not keep the old secret valid. 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 rotated the signing secret, and every delivery, replays included, is re-signed with the current one. Add the new secret to your receiver’s configuration, then drop the old one once a delivery has verified against the new one.

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 events that occurred while the subscription was disabled. The platform never records a delivery for those events, so there is nothing to replay once deliveries resume. If you try to replay one anyway, the console refuses the request and explains why. Before you re-enable, click Send test ping: it is allowed even while the subscription is disabled, so you can confirm your endpoint is reachable first.

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 actually happened in that mode. Not every event type in the list produces deliveries yet, so check which ones do on 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?.