Dead Letter Queue

Failed webhook deliveries are preserved in the Dead Letter Queue (DLQ) for inspection and replay.

What is the Dead Letter Queue?

The DLQ is a holding area for webhook deliveries that have exhausted all retry attempts. Instead of being silently dropped, these deliveries are preserved with full context so you can:

Understand why delivery failed
Inspect the original payload and all retry attempts
Replay deliveries after fixing the issue
Audit failed deliveries for compliance

When Do Webhooks Go to the DLQ?

A delivery is moved to the DLQ when:

All retry attempts have been exhausted (default: 6 attempts)
The endpoint has been disabled or deleted
The delivery has been pending for too long (stale delivery timeout)

Common failure reasons:

Endpoint returning 5xx errors consistently
Endpoint unreachable (DNS failure, connection timeout)
TLS certificate issues
Endpoint returning 4xx errors (client-side issue)

Inspecting DLQ Entries

Query failed deliveries via the API:

curl "https://hooksniff-api-1046140057667.europe-west1.run.app/v1/webhooks?status=failed" \
  -H "Authorization: Bearer hr_live_YOUR_KEY"

Response includes full delivery details:

{
  "id": "wh_xyz789",
  "endpoint_id": "ep_abc123",
  "event": "order.created",
  "status": "failed",
  "attempt_count": 6,
  "attempts": [
    { "attempt": 1, "status": 500, "error": "Internal Server Error", "timestamp": "2026-01-15T10:30:00Z" },
    { "attempt": 2, "status": 500, "error": "Internal Server Error", "timestamp": "2026-01-15T10:30:10Z" },
    { "attempt": 3, "status": 500, "error": "Internal Server Error", "timestamp": "2026-01-15T10:30:40Z" },
    { "attempt": 4, "status": 500, "error": "Internal Server Error", "timestamp": "2026-01-15T10:32:40Z" },
    { "attempt": 5, "status": 500, "error": "Internal Server Error", "timestamp": "2026-01-15T10:42:40Z" },
    { "attempt": 6, "status": 500, "error": "Internal Server Error", "timestamp": "2026-01-15T11:12:40Z" }
  ],
  "payload": { "order_id": "12345", "total": 99.99 },
  "created_at": "2026-01-15T10:30:00Z"
}

Replaying Failed Webhooks

Once you've fixed the issue, replay the delivery:

# Replay a single delivery
curl -X POST https://hooksniff-api-1046140057667.europe-west1.run.app/v1/webhooks/wh_xyz789/replay \
  -H "Authorization: Bearer hr_live_YOUR_KEY"

Replay resets the attempt counter and re-queues the delivery with a fresh retry schedule. You can also replay from the dashboard with one click.

DLQ Retention

DLQ entries are retained based on your plan:

Plan	Retention	Max DLQ Entries
docs.developer	7 days	100
docs.startup	14 days	1,000
Pro	30 days	5,000
docs.enterprise	Custom	Custom

After retention expires, DLQ entries are permanently deleted. Export important data before it expires.