Same charge, two IDs, one refund too many
You put a gateway in front of your webhook endpoint. It verifies the provider, queues the event, retries on your behalf, and signs every delivery to you with Standard Webhooks. Your handler verifies webhook-signature, inserts webhook-id into a unique-keyed table, and skips anything it has seen before. Clean. Textbook.
Then Stripe sends the same charge.refunded event twice, which its documentation tells you it may occasionally do. The gateway accepts both requests, because from where it sits they are two inbound HTTP requests. Each becomes its own gateway event. Each gets its own ID. Your dedupe table sees two different webhook-id values, inserts both, and your refund side effect runs twice.
Nothing in that chain is broken. Both signatures are valid. The ID is stable across the gateway's own retries, as promised. You deduplicated on an identifier that describes the hop, and the duplicate happened one hop earlier.
What Hookdeck shipped on November 5
On November 5, 2026, Hookdeck's Event Gateway added Standard Webhooks in both directions. On the way in, webhook and HTTP sources can now verify Standard Webhooks signatures, alongside the HMAC, Basic Auth and API key verification they already supported. On the way out, you can pick Standard Webhooks as the authentication method on an HTTP, CLI or Mock API destination and give it your endpoint's whsec_ secret. The CLI cannot set that on a destination yet, so it goes through the dashboard or the API.
The outbound request carries the three headers the spec defines: webhook-id, webhook-timestamp and webhook-signature. The signature is an HMAC-SHA256 over the ID, the timestamp and the body. The changelog makes one promise that matters for this article: the webhook-id stays the same across attempts, so your endpoint can deduplicate on it.
And one sentence that matters even more: it is the original sender's webhook-id when the request had one, and otherwise the Hookdeck event ID.
Sensible design. It also means two different identifiers share one header name, and which one you get depends on a provider you may not have looked at in a year.
The header means different things per source
If the provider upstream of the gateway already speaks Standard Webhooks, the ID passes straight through. A sender that signs this way assigns one message ID per event and reuses it on every attempt, so a duplicate from the provider arrives at your endpoint carrying the same webhook-id as the original. Your dedupe table catches it. That case works end to end.
If the provider uses its own scheme, the inbound request has no webhook-id to forward. Stripe signs with Stripe-Signature and puts the event ID, the evt_ value, in the body. GitHub sends a delivery GUID in X-GitHub-Delivery. Neither arrives as webhook-id, so the gateway falls back to its own event ID. That ID is stable across the gateway's retries to you, and it is fresh for every inbound request the gateway accepts.
Same header, same verification code, same dedupe table. End-to-end deduplication for some sources, hop-only for others. Nothing in the request tells you which case you are in. You find out from the docs, or from a double refund.
Why the gateway's retries are the easy half
There are two retry loops in a gateway setup, and they fail differently.
The first loop runs between the gateway and you. Your endpoint times out, returns a 503, or drops the connection after doing the work, and the gateway tries again. Every one of those attempts carries the same webhook-id, whichever source it came from. This is the loop people picture when they say "dedupe on the webhook ID". It is covered.
The second loop runs between the provider and the gateway, plus whatever the provider does on its own: duplicate emissions, manual resends from the provider's dashboard, a replay after a provider-side incident. A gateway that acknowledges fast makes provider retries rare. Rare is still more than zero, and provider-side duplicates need no failure at all. Every one of those becomes a new inbound request. For a non-Standard-Webhooks source, every new inbound request is a new gateway event with a new ID.
If your gateway offers deduplication at ingestion, that can close the second loop before it reaches you. Turn it on. Keep idempotency in your handler anyway. Ingestion dedupe lives in someone else's configuration, and nobody reviews that in a pull request.
Deduplicate on the provider's event ID
The fix is the one we keep coming back to in the idempotency post: pick a key for the thing that happened. The HTTP request that told you about it is the wrong thing to key on.
For Stripe that is the evt_ ID in the body. For a Standard Webhooks sender that is the webhook-id, because the sender assigned it and it survives the gateway untouched. For anything else, find the provider's event identifier and use that. Keep the transport ID as a log field and a trace attribute. Just don't put the unique constraint on it.
type Source = "stripe" | "github" | "openai";
// Returns the key that identifies the provider's event, not the delivery.
export function eventKey(source: Source, body: any, headers: Headers): string {
switch (source) {
case "stripe":
// Stripe's event ID lives in the body: evt_...
return `stripe:${body.id}`;
case "github": {
const delivery = headers.get("x-github-delivery");
if (!delivery) throw new Error("missing X-GitHub-Delivery");
return `github:${delivery}`;
}
case "openai":
// Standard Webhooks sender: the gateway forwards the sender's own ID.
return `openai:${headers.get("webhook-id")}`;
}
}
Notice the GitHub branch assumes the gateway forwards the provider's original headers. Check that, for your gateway and for every source, before you rely on it. A body field survives forwarding. A header is a configuration detail.
One table, many senders: namespace the key
The moment two sources share a dedupe table, a bare ID becomes a collision waiting for a quiet afternoon. Most provider IDs will never collide in practice. You are still betting your side effects on "in practice" across vendors who never agreed on a format.
Prefix every key with the source, as in the sample above, and make the source come from something you control. With a gateway in front, the cleanest signal is the destination path. Give each connection its own route on your side, such as /hooks/stripe and /hooks/github, and derive the source from the route. Never from the request body.
CREATE TABLE processed_events (
event_key text PRIMARY KEY, -- e.g. 'stripe:evt_...'
delivery_id text NOT NULL, -- the webhook-id you received, for tracing
received_at timestamptz NOT NULL DEFAULT now()
);
Keep delivery_id next to the event key. It pays off during an incident: when one event_key shows up with two different delivery_id values, you are looking at an upstream duplicate that the gateway turned into two events. Your dashboards will not show you that any other way.
Your signature check now vouches for the gateway
Switching a destination to Standard Webhooks changes what your signature check proves. Before, your handler verified Stripe-Signature against Stripe's secret and knew the body came from Stripe. Now it verifies webhook-signature against a secret you gave the gateway. It knows the body came from the gateway.
That is a reasonable trade. The gateway already verified the provider on the way in, and you get one verification path for every source. Five became one. But be honest about what moved. Your trust boundary is now the gateway's source configuration. If someone disables inbound verification on a source, or a new source gets created with none, your endpoint keeps accepting perfectly signed deliveries of unverified input.
It also changes what the signature covers: the body the gateway sends you. If you apply transformations at the gateway, you are verifying the transformed body, and the provider's original signature, even if forwarded, will no longer match it. We covered that trap in the gateway transformation post. The short version: decide which signature your handler is responsible for, and stop half-checking the other one.
Re-signed attempts and the timestamp window
The changelog also says the gateway signs every attempt again, retries included. Good. It fixes a problem we wrote about in retries carrying expired signatures: a sender that signs once and retries for hours hands you a webhook-timestamp that ages out of a five-minute tolerance by the third attempt.
For deduplication the consequence is subtle. Each attempt is freshly signed, so the timestamp tells you when that attempt left the gateway. It says nothing about when the event happened. Do not use webhook-timestamp as a secondary dedupe key, and do not use it to order events. Two attempts of the same event will carry different timestamps and the same ID. Two different events can easily carry the same second.
If you need event time, read it from the payload. Stripe's created field, for instance, is the event's creation time and does not change when the event is redelivered.
A verifier that does both checks
Here is the shape of a handler that verifies the gateway, extracts the right key, and deduplicates on it. It uses the official standardwebhooks package for Node.
import { Webhook } from "standardwebhooks";
const wh = new Webhook(process.env.GATEWAY_WHSEC!);
export async function handle(req: Request, source: Source): Promise<Response> {
const raw = await req.text();
const headers = Object.fromEntries(req.headers);
let body: any;
try {
body = wh.verify(raw, headers); // throws on bad signature or stale timestamp
} catch {
return new Response("invalid signature", { status: 401 });
}
const key = eventKey(source, body, req.headers);
const deliveryId = req.headers.get("webhook-id") ?? "";
const inserted = await db.query(
`INSERT INTO processed_events (event_key, delivery_id)
VALUES ($1, $2) ON CONFLICT (event_key) DO NOTHING`,
[key, deliveryId]
);
if (inserted.rowCount === 0) return new Response(null, { status: 204 });
await enqueue(source, body);
return new Response(null, { status: 202 });
}
Two things to notice. Verification runs on the raw text, before any parsing. And a duplicate gets a 2xx, so neither retry loop keeps trying. A duplicate is a success that already happened.
Where you insert the key matters too. Insert first and enqueue second, and a crash between the two loses the event. In production, write the key and the job in one transaction, or insert the key only when the job completes.
Testing the hop you cannot see
A test that sends one request to your endpoint will never show this failure. You need two inbound requests for the same provider event, going through the gateway, and an assertion that your side effect ran once.
Most providers let you resend an event from their dashboard or CLI. Point that at a staging connection. Send the event, let it process, resend it, and check: your processed-events table has one row for the event key, that row's history shows two different delivery IDs if the source is not Standard Webhooks, and the downstream effect, the email, the refund, the ledger entry, happened exactly once.
Repeat with a Standard Webhooks source and confirm the delivery IDs match. If they don't, something between the sender and you is mangling the ID, and staging is where you want to learn that.
Run this every time you add a source. The gateway made that a five-minute job. Your dedupe logic got no simpler.
Frequently asked questions
Should I stop deduplicating on webhook-id entirely? No. For a source that already speaks Standard Webhooks, the forwarded webhook-id is the sender's own event identifier, so it is the right key. The mistake is treating it as an event identifier for every source. Store it on every delivery, and decide per source whether it or a body field is your unique key.
Does the gateway's fallback event ID change when the gateway retries a delivery to me? No. According to Hookdeck's changelog the webhook-id stays the same across attempts, whichever source the event came from. It only differs when the gateway accepted two separate inbound requests, which is the provider-side duplicate case this article is about.
Can I verify both the provider's signature and the gateway's signature? You can, if the gateway forwards the provider's original headers and the body is untouched. In practice it doubles your secret management for little gain, and any transformation breaks the provider check. Pick the gateway signature as the one your handler enforces, and make sure inbound verification is switched on for every source in the gateway.
What if a provider has no stable event ID at all? Then you have to build one from the payload, such as the object ID plus a version or an updated-at timestamp, and accept that it is a heuristic. Treat that source as one where duplicates can slip through and make the downstream effect idempotent on its own terms, for example with an upsert.