Replaying a webhook delivery — consent rechecked before anything is sent
Who this guide is for: customer ADMINISTRATORS and technical teammates who run outgoing webhooks (developers). Replay needs a seat with the message-write permission — read-only seats are refused.
Outgoing webhooks deliver your business's events to your HTTPS address. When a delivery has already happened (or failed) and you want it sent again, you replay it, quoting the event id of the original delivery. Replay is per attempt — each recorded attempt in the delivery history can be replayed, and each replay becomes a new attempt row with its own truthful outcome; history is never rewritten.
The rule this guide is really about: a contact's current consent is rechecked before any message leaves the platform. A contact who opted out since the original delivery stops the replay cold.
About the example. The replay was exercised against a simulated receiver injected through the platform's delivery seam — no live HTTPS address was contacted, and no live send of any kind was performed in any run behind this guide. Every business, contact and consent state in the run is synthetic.
Step 1 — Who may even try
The door is closed in layers, each before anything is sent:
- Not signed in → 401.
- A read-only (viewer) seat → 403 SCOPE_DENIED — replay needs the member-level message-write authority, not just read access.
- A member of a different business asking for your subscription → 404 — a foreign subscription is indistinguishable from a nonexistent one. Under the surface, the other business's access sees zero rows of your deliveries (enforced by row-level security), so the 404 is storage truth, not a polite mask.
One more guard: when the platform is built with no receiver configured at all, replay answers 404 rather than silently falling back to some test receiver. Nothing is sent by accident.
Step 2 — Consent is rechecked now, not trusted from then
In the test, the contact had two records: a legacy record still marked opted-in, and the current normalized record marked opted-out. Replay reads the current record, so the replay attempt was refused:
- Answer: 409 CONSENT_WITHDRAWN.
- Zero messages sent — the refusal happens before the send.
- The original delivery's stored payload was re-read after the refusal and is byte-identical — a refused replay changes nothing.
This is the whole point of consent-gated replay: the original delivery may have been legitimate when it happened, but the contact's current state governs.
Step 3 — A permitted replay, one at a time
After the contact's state was back to opted-in, the replay went through:
- Only one replay of the same original at a time. While one is in flight, a second answers 409 REPLAY_IN_PROGRESS — exactly one delivery in flight. When the first finishes, the lock frees.
- The replay answer is a truthful record, not just "ok": the attempt number, outcome, whether it was deduplicated, the receiver's HTTP status and the delivery id. The successful replay was attempt 2, outcome "delivered".
- The delivered message is signed with the subscription's own secret, and the posted event's data equals the original snapshot's data.
Step 4 — A failing receiver is recorded as a failure
The next replay (the receiver now answering HTTP 500) produced attempt 3, outcome "failed", response status 500, a distinct delivery id, and a new history row. After three attempts the history read, in order: attempts 1/2/3 with outcomes delivered, delivered, failed — and every row's stored payload exactly equal to the original snapshot. The payload is immutable; only attempts accumulate.
What to do when a replay is refused
| Answer | Meaning | What to do |
|---|---|---|
| 401 | Not signed in | Sign in and retry |
| 403 SCOPE_DENIED | Your seat is read-only for this action | Ask a seat with the message-write permission, or have your role updated by an admin |
| 404 | Subscription or event is not yours (or no receiver is configured) | Check the subscription id, your business selection, and your webhook configuration |
| 409 CONSENT_WITHDRAWN | The contact has opted out since the original | Nothing to fix — this refusal is correct; do not attempt to work around it |
| 409 REPLAY_IN_PROGRESS | Another replay of the same original is running | Wait, then read its saved outcome before retrying |
Evidence record (kept for honesty). The FULL3747-PG lane executed the
mounted P15 replay suite against the real buildApp composition on a
real ordinary-role throwaway PostgreSQL 16 cluster over real loopback HTTP,
on the combined candidate:
- Suite 12 —
webhook-replay.build-app-pg.test.ts: 5/5 subtests passed (2026-10-24T23:24:38Z → 23:24:55Z, exit 0), verbatim TAP receipttools/zcode-integration3723/runtime/FULL3747-PG/logs/12-replay.tapin the PG lane worktreeC:/CT-ZC-FULL3747(git-ignored). - A second independent fresh-PG cycle was green again
(
c2-12-replay.tap; lane ledger "CYCLES 1+2 COMPLETE AND GREEN", 2026-10-24T23:44:30Z,C:/CT-ZCODE-FULL3747/lane-pg-ledger.json).
Standing: combined-candidate, local evidence — the replay route is
mounted in the candidate's app.ts (exercised through the real
buildApp). Chief acceptance and publication are OPEN. A sibling guides
branch (codex/zcode-3456-guides, not part of this guide's base) documents
the on-screen Replay control and confirm gate for the same journey; this
guide documents the mounted API contract underneath. No live or Main-built
deployment is claimed.