Summary
To process webhooks idempotently, verify the signature on the raw body, record each event ID under a unique constraint before acting on it, return a 2xx response quickly, and do slow work from a queue. Providers such as Stripe deliver at least once and retry for up to three days, so the same event can arrive more than once and out of order.
Every major enterprise platform (Stripe, PayPal, GitHub, Twilio) operates under at-least-once delivery semantics. If a network glitch or temporary database lock (see relational database performance and lock contention) delays an HTTP 200 response, the provider's retry runner will resend the identical webhook payload minutes or seconds later.
Without robust idempotency guards, duplicate orders are minted, subscription tiers are toggled inconsistently, and customers are charged multiple times.
Cryptographic Verification & Replay Protection
Before parsing webhook bodies, verify the HMAC-SHA256 signature over the exact raw bytes received and reject timestamps outside your tolerance. Stripe's libraries default to 5 minutes (300 seconds), and Stripe warns that a tolerance of 0 disables the recency check. For Stripe, the signed message is the t= timestamp from the Stripe-Signature header, a ., and the raw body; only v1 signatures count (Stripe webhook docs):
export async function verifyStripeSignature(
rawBody: string,
header: string,
secret: string,
toleranceSec = 300
): Promise<boolean> {
const parts = header.split(',').map((p) => p.split('='));
const t = parts.find(([k]) => k === 't')?.[1];
const v1s = parts.filter(([k]) => k === 'v1').map(([, v]) => v);
if (!t || v1s.length === 0) return false;
if (Math.abs(Date.now() / 1000 - Number(t)) > toleranceSec) return false;
const encoder = new TextEncoder();
const key = await crypto.subtle.importKey(
'raw',
encoder.encode(secret),
{ name: 'HMAC', hash: 'SHA-256' },
false,
['verify']
);
const message = encoder.encode(`${t}.${rawBody}`);
for (const sig of v1s) {
if (await crypto.subtle.verify('HMAC', key, hexToBuffer(sig), message)) return true;
}
return false;
}
Several v1 signatures can appear while an endpoint secret is being rolled, so check each one. In production, prefer the provider's official library (for Stripe, stripe.webhooks.constructEvent, or constructEventAsync on Workers); other providers such as GitHub and Twilio use different header formats.
Squarespace commerce webhooks follow the same model: each notification is signed with HMAC-SHA256 in the Squarespace-Signature header, delivery is retried for up to 48 hours, and the same notification can occasionally arrive twice, so deduplicate on its id. For how those webhooks fit into the platform, see Squarespace backend and frontend technologies used.
Atomic Compare-And-Swap (CAS) Deduplication
To prevent race conditions when twin webhooks arrive at separate edge nodes simultaneously, the system claims execution atomically:
INSERT INTO payment_idempotency (idempotency_key, status, locked_until)
VALUES (?, 'processing', datetime('now', '+30 seconds'))
ON CONFLICT(idempotency_key) DO UPDATE SET
status = CASE WHEN locked_until < datetime('now') THEN 'processing' ELSE status END
RETURNING status;
If the claim fails or the status is already 'settled', the duplicate invocation exits immediately with HTTP 200, protecting business invariants.
Key the claim on the provider's event ID, not on the event's created timestamp: Stripe notes that distinct events can share a timestamp and that delivery order is not guaranteed, so handlers should fetch the current object state rather than assume invoice.created arrives before invoice.paid.
Zero Locks Held During Third-Party Network I/O
Processing webhooks often requires notifying customers, firing internal alerts, or executing follow-on accounting entries. SazM decouples these side effects:
// Acknowledge webhook in < 20ms
await claimIdempotencyKey(d1, eventId);
await env.OUTREACH_QUEUE.send({ type: 'payment_settled_notification', eventId });
return Response.json({ received: true });
The same rule keeps your database healthy: never hold a row lock while waiting on a provider API (see database lock contention).
Frequently Asked Questions
How long does Stripe retry a failed webhook?
In live mode Stripe retries for up to three days with exponential backoff; sandbox events are retried three times over a few hours. You can also resend an event from the Dashboard for up to 15 days, or with stripe events resend for up to 30 days.
Can the same webhook event arrive twice even after I returned 200?
Yes. At-least-once delivery means duplicates happen occasionally, and Stripe sometimes generates two separate Event objects for the same change. Log processed event IDs, and for the second case also compare the data.object ID together with the event type.
How much does it cost to fix duplicate or missed webhook events?
One confirmed webhook problem is a $99 fixed-price fix delivered within 48 hours of receiving access, including root-cause diagnosis, a test-mode check on staging and written proof. Typical agency hourly rates are higher and open-ended, while very low marketplace gig prices rarely include root-cause diagnosis, staging tests or a guarantee.
Getting a signature error instead? See the Stripe webhook "No signatures found" fix.
If your live Stripe webhooks are already failing, see the $99 fixed-price Stripe webhook fix.
Seeing 429 insufficient_quota from an AI API instead? See the OpenAI 429 quota error fix.