Delivery

Delivery Behavior

• Requests are sent as HTTP POST with Content-Type: application/json

• Your endpoint must respond with 2xx within 30 seconds

• Non-2xx responses or timeouts trigger retries

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

Failed deliveries are stored in the DLQ for manual inspection and replay.

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

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

Each event includes a unique event_id. Use this to deduplicate events in case of retries or replays.

Disabling Webhooks

If your endpoint fails consistently (10+ consecutive failures), the webhook may be automatically deactivated. You'll receive an email notification.