Skip to content
SazM Senior dev · Fixed price
Find a service
Where can I help?

Use arrow keys to browse, Enter to open, and Escape to close.

11 destinations

Client Login Get a fix →

Platform Hardening · 9 min read

Resilient Webhook Ingestion: Cryptography & Idempotency

Design resilient webhook architectures with HMAC-SHA256 signature verification, atomic CAS idempotency claims, and zero duplicate billing.

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.

// SazM ENGINEERING DISPATCH · PRODUCTION REMEDIATION

Senior Engineering Without Agency Overhead

// TRACK A · FIXED-PRICE FIXES (48H SLA)

Single Urgent or Speed Fix

Immediate code-level fixes with zero discovery calls. Emergency root-cause patch within 48 hours for $99, or full Core Web Vitals & speed remediation with before/after audit for $199. 100% money back if the agreed root cause cannot be fixed.

// TRACK B · SENIOR RETAINER & BUILDS

Monthly Plan or Custom Scope

Direct senior-level capacity embedded in your stack. Dedicated monthly engineering ($999/mo, 1 active task at a time, 24–48h PR delivery, pause or cancel anytime), or fixed-scope architectural milestones delivered within a 24h written quote.

✓ 20+ years engineering ✓ 100+ projects in the portfolio ✓ Fixes within 48 hours ✓ 100% money back if not fixed
1 Active Task at a Time
Requests are completed one by one in your priority order. As soon as an active task is shipped, tested, and approved, work starts immediately on your next task within our 24–48h SLA.
48h Emergency SLA
Clock starts as soon as site access details are provided. Delivered with full backup taken first, isolated staging testing, and 100% money back if not fixed.
WordPress Care Plan Scope
Weekly core and plugin updates pre-tested in staging, daily offsite encrypted backups, 24/7 uptime monitoring, and proactive security patching.
Pay Nothing Upfront
Zero upfront payment or credit card required. A 20-Year Senior Engineer diagnoses your issue, reproduces it on isolated staging, and deploys the fix. You only pay once you verify the staging reproduction or production fix.