How to Replay Failed Webhooks Safely With Hookdeck and Codex

Do not start a webhook incident by replaying the entire failed queue. First prove that the destination is healthy and idempotent, inspect one failed event and all of its delivery attempts, replay that single event, and verify one intended side effect. Expand the recovery batch only after the canary succeeds.

That sequence matters because webhook delivery is commonly at least once. A retry or replay can repeat a charge, message, booking, or record unless the destination recognizes the event as work it has already completed.

This workflow reflects Hookdeck's official documentation and the active Actions discoverable through Aident Loadout on August 27, 2026. Action names and schemas can change, so discover the live contract before every incident.

The Safe Recovery Sequence

If you have not yet connected agent tools through a managed integration boundary, start with How to Use Aident Loadout.

Discover the Current Hookdeck Actions

Install or update the public Aident CLI from the canonical guide:

Follow https://aident.ai/SETUP.md

Confirm account and Vault state, then search by job:

aident account auth status
aident vault vault --action status

aident capabilities search --targetEnv staging \
  --queries '["list open Hookdeck delivery issues", "find failed Hookdeck events and attempts", "replay one Hookdeck event"]' \
  --types '["action"]'

On August 27, the live staging catalog exposed Hookdeck Actions for these jobs:

• list detected issues;

• list and filter events;

• list delivery attempts for an event; and

• replay one event.

Inspect each current schema before using it:

aident capabilities get \
  --name "<current Hookdeck event-list Action>" \
  --parts '["description","inputSchema","outputSchema"]'

The catalog currently lets you bound events by status, response status, connection, destination, creation time, attempt count, and cursor. Attempts can be narrowed to one event ID. The replay Action accepts one evt_ event ID. Do not treat this article's names as an execution contract if discovery returns a newer version.

1. Bound the Incident Before Reading the Queue

Start with the smallest window that explains the alert. Record:

• the Hookdeck connection and destination;

• the first and last known failure times in UTC;

• the expected HTTP status and actual response class;

• whether the source is still sending new events;

• the business operation behind each event;

• the maximum safe recovery rate.

List open delivery issues and failed events only for that boundary. A useful read plan is an open delivery issue query followed by an event query with the relevant webhook_id, a created_at range, and a failed response filter. Paginate with returned cursors instead of silently assuming the first page is complete.

Do not bulk retry at this stage. A broad queue can mix the incident with old failures, expected rejects, test traffic, or events already recovered through another path.

2. Inspect Every Attempt for One Event

Select one representative event that has a reversible or easily verified effect. Use the event ID to retrieve every recorded attempt, then compare:

• request identity and timestamp;

• destination and connection;

• response status and response body;

• timeout or transport error;

• attempt order and retry interval;

• whether an attempt may have reached the destination before the client observed failure.

The last case is the dangerous one. A timeout does not prove the destination did nothing. It may have committed the business change and lost the response. Treat an ambiguous timeout as possibly successful until the downstream system proves otherwise.

Hookdeck's documentation distinguishes a retry of an event delivery from replaying an original request through processing and routing again. Pick the operation that matches the recovery job. Do not use replay as a generic synonym for every retry path.

3. Prove Idempotency at the Destination

Hookdeck documents an at-least-once guarantee and recommends idempotent handlers. Its deduplication feature is best effort, so the destination still needs its own durable guard.

A reliable handler usually follows this order:

1. Verify the provider signature against the unmodified request body.

2. Extract a stable provider event ID or another approved business idempotency key.

3. Atomically insert that key into a table with a uniqueness constraint.

4. If the key already exists with a completed outcome, return success without repeating the side effect.

5. Perform the business operation and record its result against the key.

6. Return a success response only when the durable outcome is known.

The idempotency key must identify the business event, not the delivery attempt. A new attempt ID for the same charge or booking should not create a second charge or booking. Define what happens after a partial failure, how long the key is retained, and how concurrent duplicates contend for the same key.

For credential and secret boundaries around this workflow, use Give AI Agents API Access Without Exposing Keys.

4. Preflight One Replay as a Canary

After the destination fix is deployed and its health check passes, prepare one exact replay input and preflight it:

aident capabilities preflight \
  --name "<current Hookdeck single-event replay Action>" \
  --input '{"event_id":"evt_reviewed_canary"}'

Stop if the schema, account, risk acknowledgement, or credit state is unresolved. The preflight is not the replay. Execution changes provider state and can trigger a downstream side effect, so a human should approve the exact event, destination, expected outcome, and stop condition before the Action runs.

After approval, execute only that reviewed input. Immediately retrieve the event's new attempt and verify the downstream business system. Success requires all of the following:

• Hookdeck recorded the intended replay and a successful delivery attempt;

• the destination accepted the event;

• exactly one intended business outcome exists;

• no duplicate charge, message, booking, or record exists;

• observability links the source event, replay, attempt, and downstream result.

An HTTP 200 alone is not enough. It proves the handler responded successfully, not that the correct business state exists exactly once.

5. Expand in Reviewed Batches

Re-query the incident boundary after the canary. Remove events that recovered automatically or through another operator. Group the remainder by destination, failure reason, and business risk.

Expand gradually with:

• an explicit event count;

• a rate below the destination's tested capacity;

• continuous success and duplicate monitoring;

• a stop threshold for error rate or unexpected side effects;

• an operator who can pause the batch;

• a reconciliation query after each tranche.

High-value or irreversible events may still require one-at-a-time approval. A bulk retry command is convenient, but convenience does not establish that every event in the filter is safe to repeat.

A Safe Prompt for Codex or Claude Code

Follow https://aident.ai/SETUP.md

Help me diagnose a bounded Hookdeck webhook incident with the installed public
aident CLI. Confirm account and Vault state. Discover current Actions in staging
by job and inspect each exact schema before execution.

Read only until I approve a replay. List open delivery issues, find failed events
for the reviewed connection and UTC window, paginate every page, and inspect all
attempts for one representative event. Treat timeouts as possibly committed.

Before proposing a replay, require evidence that the destination is healthy and
uses a durable business-event idempotency key with an atomic duplicate check.
Preflight exactly one event and report the Action, input, account, expected side
effect, verification query, and stop condition. Do not replay, bulk retry, edit,
or delete provider data without my explicit approval.

After an approved canary, verify one Hookdeck delivery and exactly one downstream
business outcome. Expand only through reviewed batches with a rate limit, stop
threshold, audit trail, and reconciliation step. Report missing evidence instead
of assuming a 2XX response proves recovery

Failure Matrix

Recover One Event

Follow https://aident.ai/SETUP.md

Inspect and recover one failed webhook with a bounded canary

Use the AI agent cost guardrails workflow when recovery can trigger billable provider work beyond the webhook delivery itself.

Method and Limitations

This workflow used the live Aident Loadout staging catalog, current Action descriptions and schemas, official Hookdeck documentation, current Google results, current Reddit discussions, and current YouTube results on August 27, 2026. It did not connect a Hookdeck account, read customer events, execute a replay, test a destination, validate a specific provider signature, or certify Hookdeck's availability, security, privacy, pricing, or delivery behavior for a particular workload. Refresh the workflow when the live Action contract, Hookdeck retry or replay semantics, or the destination's idempotency design changes.

Sources

• Aident Loadout setup guide, reviewed August 27, 2026.

• Live Aident Loadout catalog and Hookdeck Action schemas, inspected August 27, 2026.

• Hookdeck retries, reviewed August 27, 2026.

• Hookdeck requests and replay, reviewed August 27, 2026.

• Hookdeck deduplication, reviewed August 27, 2026.

• Hookdeck receive-webhooks guide, reviewed August 27, 2026.

• Hookdeck webhook troubleshooting guide, reviewed August 27, 2026.

• Current Google results for webhook replay failed webhook duplicate events, collected through a connected search account on August 27, 2026.

• Current Reddit results for webhook replay failed duplicate, collected through a connected account on August 27, 2026.

• Current YouTube results for webhook replay failed webhooks Hookdeck, collected through a connected account on August 27, 2026.

Re-run the canary and reconciliation sequence whenever the handler, routing, retry policy, or business side effect changes.