Build an idempotent at-least-once consumer

Delivery is at least once by design, so exactly-once lives in your consumer. Stack three defenses: collapse provider retries at ingestion, let only verified events through, and make your receiver idempotent on a stable id — so a duplicate delivery is a harmless no-op.

Collapse retries at ingestion

identifier dedup keys on the webhook-id header (then a provider event id), so most provider retries never become a second event. It’s load reduction, not a guarantee — the next two layers cover the rest.

wbhk endpoints update <endpoint-id> --dedup-mode identifier --dedup-window 600

Deliver only what you verified

--require-verified forwards only events whose source was authenticated (the verified and authenticated states); an unattempted event is dropped by the filter, and a failed one is blocked outright. Your receiver can trust that a signed delivery is genuine.

wbhk subscriptions add <endpoint-id> <destination-id> --require-verified

Dedup on webhook-id at the receiver

The forwarded event carries a stable webhook-id. Record processed ids and short-circuit repeats — this is the layer that actually makes the consumer idempotent.

// pseudocode
if (await seen(req.headers["webhook-id"])) return res.status(200).end();
await process(req.body);
await markSeen(req.headers["webhook-id"]);

Duplicate deliveries and provider retries are never metered — only the first dispatch counts. See what counts as an event.

How-to guides

Providers

Recipes

Build an idempotent at-least-once consumer