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:

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.

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:

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:

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:

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.