Dead Letter Queue

The dead letter queue holds events that exhausted every retry attempt. Instead of silently dropping them, hookstream flags them as permanently failed so you can inspect and retry on your own schedule.

How an event reaches the DLQ

Inspect DLQ events

Filter failed events anywhere you can filter events:

curl "https://hookstream.io/v1/events?status=failed" \
  -H "X-API-Key: $HOOKSTREAM_API_KEY"

hookstream events list --status failed

You can also open the Events page in the dashboard and set Status = Failed, or jump straight to the Issues page where related failures are already grouped.

Every failed event keeps its full history — status codes, latency, response headers, and error messages for each attempt.

Retry DLQ events

curl -X POST https://hookstream.io/v1/events/evt_abc/retry \
  -H "X-API-Key: $HOOKSTREAM_API_KEY"

curl -X POST https://hookstream.io/v1/delivery-attempts/att_xyz/retry \
  -H "X-API-Key: $HOOKSTREAM_API_KEY"

curl -X POST https://hookstream.io/v1/issues/iss_123/retry \
  -H "X-API-Key: $HOOKSTREAM_API_KEY"

Retries create new delivery attempts. The originals are preserved for audit, so your history stays intact.

Check the destination's circuit breaker before mass retrying. If the endpoint is still down, every retry just fails again and re-opens the breaker.

Best practices

• Alert on DLQ growth. Create a dlq alert rule so you notice before your customers do.
• Use the Issues page for bulk work. One POST /v1/issues/:id/retry handles every event in a group.
• Look at error breakdown in Metrics. Clusters of identical errors usually point at one fix that clears the whole queue.
• Tune retries for flaky destinations. If a destination reliably recovers within hours, extend retry_intervals so retries outlive transient outages.

Next Steps