Dead-Letter Queue

The DLQ is the ledger of deliveries that exhausted normal retry behavior and still need operator attention. Use it when you want to inspect terminal failures, export evidence, or create fresh replay deliveries from failed rows.

DLQ model

DLQ rows are separate records, not just a delivery status flag. Each entry ties back to:

  • the source delivery
  • the terminal attempt
  • replayability state based on retained source and dispatch payload artifacts

DLQ re-drive does not mutate the failed delivery in place. It creates a new replay delivery using the same replay coordinator path as normal delivery replay.

Auth model

  • Name
    Public API
    Type
    project API key
    Description

    DLQ list, detail, export, and single re-drive are project-authenticated Public API routes. Bulk re-drive is also project-authenticated and requires Starter+.

  • Name
    Dashboard
    Type
    session auth
    Description

    The dashboard provides DLQ list, detail, single re-drive, and auto-refreshed views for operators.

  • Name
    CLI / SDK
    Description

    The CLI and SDK cover core DLQ inspection and recovery flows.

Inspection, export, and re-drive

The normal operator sequence is:

  1. inspect GET /v1/dlq or GET /v1/dlq/{id}
  2. export evidence with GET /v1/dlq/export when you need retained source payload snapshots
  3. run POST /v1/dlq/{id}/re-drive to create a fresh replay delivery

Important behavior:

  • export includes the same filters and cursor semantics as the normal list route, but each export page is capped at 20 rows and payload bodies are base64-encoded
  • detail includes replayable so you can tell whether the required payload artifacts still exist
  • re-drive can return 409 when the source payload or dispatch snapshot has already expired
  • re-drive can safely be retried after certain handoff failures because pending unsequenced replays are reused

Bulk recovery and replayability

Bulk recovery is the Starter+ async path:

  • POST /v1/dlq/bulk-re-drive creates a job over a frozen snapshot of matching DLQ rows
  • poll GET /v1/bulk-operations/{id} for counts and per-item progress

Create a bulk DLQ recovery job

curl https://api.hooksbase.com/v1/dlq/bulk-re-drive \
  -H "Authorization: Bearer swk_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: recover-dlq-orders-2026-04-23" \
  -d '{
    "filters": {
      "webhookId": "wh_123",
      "from": 1740000000000,
      "to": 1740086400000
    },
    "maxItems": 100
  }'

Poll recovery progress

curl https://api.hooksbase.com/v1/bulk-operations/bulk_123 \
  -H "Authorization: Bearer swk_..."

How DLQ differs from direct replay:

  • direct replay starts from a known delivery row
  • DLQ re-drive starts from a dead-letter record created after retry exhaustion
  • both still depend on retained source payload and any retained transformed dispatch snapshot
  • GET /v1/dlq
  • GET /v1/dlq/{id}
  • GET /v1/dlq/export
  • POST /v1/dlq/{id}/re-drive
  • POST /v1/dlq/bulk-re-drive
  • GET /v1/bulk-operations/{id}

Common mistakes

  • Treating DLQ re-drive as an in-place retry. It always creates a new replay delivery.
  • Waiting until retention expires and then expecting replayable entries to remain recoverable.
  • Using DLQ export as the primary delivery history feed instead of an operator recovery tool.
  • Forgetting that bulk re-drive runs asynchronously through a bulk-operation job.

Was this page helpful?