Dead Letter Queue

The dead letter queue (DLQ) captures webhook deliveries that failed after all retry attempts.

How It Works

When a webhook delivery fails and all retries are exhausted:

1. The message state changes to dlq
2. The message ID, webhook URL, failure reason, and timestamp are recorded
3. The entry remains in the DLQ until you inspect and handle it

List DLQ Entries

curl http://localhost:8080/dlq \
  -H "X-API-Key: your-api-key"

Response:

[
  {
    "message_id": "msg-123",
    "webhook_url": "https://yourapp.com/webhook",
    "failed_at": "2025-03-19T12:00:00Z",
    "reason": "connection refused"
  }
]

Replay a Failed Message

Re-deliver a message that's in the DLQ:

curl -X POST http://localhost:8080/replay/msg-123 \
  -H "X-API-Key: your-api-key"

This re-queues the message for delivery. See Replay for more details.

Remove a DLQ Entry

After handling a failed message (or deciding to discard it), remove it from the DLQ:

curl -X DELETE http://localhost:8080/dlq/msg-123 \
  -H "X-API-Key: your-api-key"

Returns 204 No Content on success.

Common Failure Reasons

Reason	What to Check
connection refused	Is your webhook endpoint running?
timeout	Is your endpoint responding within 30 seconds?
status 500	Check your application logs for errors
DNS resolution failed	Is the webhook URL correct?
TLS handshake failed	Is the endpoint's SSL certificate valid?

Monitoring

In production, monitor DLQ size to catch delivery issues early. MXHook exposes Prometheus metrics — see Monitoring.