History & DLQ

Delivery history is the append-only log of every outbound delivery attempt, and the dead-letter queue (DLQ) captures the deliveries that failed terminally. Every attempt writes a row to /v1/delivery/items with its status, HTTP code, error code, and request/response bodies (truncated to 10 KB each). Terminal failures (retry ladder exhausted or permanent 4xx) escalate to /v1/delivery/dlq. Both are fully replayable — replay enqueues a new attempt while preserving the deterministic idempotency key, so receivers that deduplicate on the key will not process the same delivery twice even after multiple replays. Replay never mutates a historic row: it enqueues a fresh attempt. The one deliberate exception is cleanup — DELETE /v1/delivery/items (optionally filtered by binding_id, destination_id, or status) removes item rows in batches and reports remaining: true until it is done; DLQ entries survive a cleanup.

The delivery items log captures the full lifecycle of each attempt with one of four statuses: in_flight, succeeded, failed, or superseded. superseded is an expected suppression, not a failure: a newer dispatch for the same subject replaced a stale one before it shipped. (A Dispatch node that a run request told to skip records a skipped dispatch on the pipeline instead, and produces no items at all.) Each row includes the attempt number, HTTP status code, error code, duration in milliseconds, and truncated request/response bodies (up to 10 KB each). Item and DLQ IDs are UUIDs, while event IDs are sequential integers for efficient ordering.

Each item records the destination the attempt actually went to. Usually that is the binding's own destination, but a per-request destination override on POST /v1/run can send an attempt somewhere else. The destination_id filter on the items list matches that effective destination, so filtering by a destination shows every attempt that reached it, including overridden ones, and excludes attempts the binding normally sends there but that were re-pointed. Older rows that predate this tracking resolve through their binding. Filter by binding_id or status to narrow further when debugging one integration.

The dead letter queue (DLQ) is your safety net for terminal failures. When the retry ladder is exhausted (default: 7 attempts over ~10 hours) or the destination returns a permanent error (e.g., 401 Unauthorized, 403 Forbidden), the failed delivery moves to the DLQ. From there you can inspect the error details, fix the destination configuration, and replay the delivery with a single click or API call. Destinations returning authentication errors are automatically disabled to prevent further failed attempts until the credentials are updated.

For best results, monitor the DLQ regularly and set up a delivery.item.failed meta-event binding to receive alerts when deliveries fail terminally. Most teams configure a notification webhook for this event so they are notified immediately rather than discovering failures during a manual review. Request and response bodies older than the configured retention period are automatically cleaned up, but row metadata (status, error code, duration) is retained indefinitely.

# List delivery attempts for a binding:
curl -s "https://api.talonic.com/v1/delivery/items?binding_id=bind_001&limit=5" \
  -H "Authorization: Bearer $TALONIC_API_KEY"

# Response:
# {
#   "items": [
#     {
#       "id": "item_abc",
#       "status": "succeeded",
#       "attempt": 1,
#       "http_status": 200,
#       "duration_ms": 142,
#       "completed_at": "2025-04-22T10:05:00Z"
#     }
#   ]
# }

# Check the DLQ for terminal failures:
curl -s "https://api.talonic.com/v1/delivery/dlq?binding_id=bind_001" \
  -H "Authorization: Bearer $TALONIC_API_KEY"

# Replay a dead-letter entry. Replay removes the DLQ entry, re-signs
# the payload with the current signing secret, resets the retry counter
# to attempt 1, and re-enqueues through the full backoff ladder
# (same idempotency key):
curl -X POST https://api.talonic.com/v1/delivery/dlq/dlq_xyz/replay \
  -H "Authorization: Bearer $TALONIC_API_KEY"
# -> { "replayed": true }

The delivery history and DLQ together provide complete observability into your outbound data flow. Every attempt is logged with precise timing, HTTP status, error classification, and truncated request/response bodies for debugging. When a delivery fails terminally, the DLQ captures the full context — which event triggered it, which binding matched, what error occurred, and how many attempts were made. Replay is safe to run multiple times because the idempotency key is deterministic: receivers that deduplicate on the X-Talonic-Idempotency-Key header will not process the same delivery twice, even after multiple replays. Destinations that return authentication errors (401, 403) are automatically disabled to prevent a cascade of failed attempts from consuming your retry budget.