Dead Letter Queue (DLQ)

Why You Would Use This

When an outbound message fails delivery and all automatic retries are exhausted, the message moves to failed_permanent status and appears in the Dead Letter Queue (DLQ). The DLQ gives you a focused view of messages that need manual attention, separate from your full message history.

Use the DLQ to:

• See which messages could not be delivered despite retries.
• Investigate the failure cause using attempt history and response details.
• Replay messages once the downstream issue is resolved.

How Messages Reach the DLQ

A message enters the DLQ when it reaches failed_permanent status. This happens when:

• All retry attempts are exhausted. Automatic retries ran their course without a successful delivery.
• The receiver returned a non-retryable status code. Certain 4xx responses (such as 400, 401, 403, 404) indicate the request itself is invalid and retrying will not help.

Retryable failures (such as 408, 429, and 5xx responses) are retried automatically before a message can reach the DLQ.

Console Workflow

1. Open Messages.
2. Filter by status failed_permanent to see DLQ messages.
3. Open a message to inspect delivery attempt history and response details.
4. Fix the downstream cause (destination misconfigured, endpoint down, authentication expired, etc.).
5. Use Replay from message details once the destination is healthy.

API Workflow

API reference:

• List DLQ messages
• Replay from DLQ

1) List DLQ messages

curl "https://api.hookbridge.io/v1/dlq/messages?limit=50" \
  -H "Authorization: Bearer YOUR_API_KEY"

The response includes cursor-based pagination. Use next_cursor from the response to fetch the next page.

2) Inspect a failed message

curl https://api.hookbridge.io/v1/messages/YOUR_MESSAGE_ID \
  -H "Authorization: Bearer YOUR_API_KEY"

3) Replay from the DLQ

curl -X POST https://api.hookbridge.io/v1/dlq/replay/YOUR_MESSAGE_ID \
  -H "Authorization: Bearer YOUR_API_KEY"

The message is re-enqueued for delivery. DLQ replays are not subject to replay count limits — you can always recover a failed message as long as the payload has not expired.

DLQ vs. Filtering Logs

You can also find permanently failed messages by filtering the logs API:

curl "https://api.hookbridge.io/v1/logs?status=failed_permanent&endpoint_id=YOUR_ENDPOINT_ID&limit=50" \
  -H "Authorization: Bearer YOUR_API_KEY"

The logs endpoint supports additional filters (endpoint, date range) that the DLQ endpoint does not. Use the DLQ for quick access to all failed messages; use logs when you need to narrow down by endpoint or time window.

Operational Tips

• Check the DLQ regularly or configure alerts to be notified when messages reach failed_permanent.
• Before replaying, confirm the downstream issue is resolved — replaying into a still-broken endpoint will result in the message failing again.
• For bulk recovery, use replay-all or replay-batch instead of replaying messages one at a time.
• Payloads are subject to retention limits. Replay before the retention window closes.