Webhook Delivery
Delivery Behavior
Section titled “Delivery Behavior”- Requests are sent as HTTP POST with
Content-Type: application/json - Your endpoint must respond with
2xxwithin 30 seconds - Non-2xx responses or timeouts trigger retries
Retry Policy
Section titled “Retry Policy”Failed deliveries are retried with exponential backoff, up to 5 attempts:
| Attempt | Delay before attempt |
|---|---|
| 1 | Immediate |
| 2 | 5 seconds |
| 3 | 30 seconds |
| 4 | 2 minutes |
| 5 | 10 minutes |
After the final failed attempt, the delivery is moved to the dead letter queue (DLQ).
Dead Letter Queue
Section titled “Dead Letter Queue”Failed deliveries are stored in the DLQ for manual inspection and replay.
DLQ Endpoints
Section titled “DLQ Endpoints”| Method | Path | Description |
|---|---|---|
| GET | /webhooks/:id/dead-letters | List dead letters |
| GET | /webhooks/:id/dead-letters/:dlqId | Get dead letter (includes payload) |
| POST | /webhooks/:id/dead-letters/:dlqId/retry | Retry a pending dead letter |
| DELETE | /webhooks/:id/dead-letters/:dlqId | Discard a pending dead letter |
| GET | /webhooks/:id/dead-letters/stats | DLQ stats (pending/retried/discarded) |
Retry a Failed Delivery
Section titled “Retry a Failed Delivery”curl -X POST https://api.tokenbot.com/v1/webhooks/wh_123/dead-letters/dlq_456/retry \ -H "X-API-Key: tb_live_your_key"Idempotency
Section titled “Idempotency”Each event includes a unique event_id. Use this to deduplicate events in case of retries or replays.
Disabling Webhooks
Section titled “Disabling Webhooks”If your endpoint fails consistently (10+ consecutive failures), the webhook may be automatically deactivated. You’ll receive an email notification.