Webhook Signature Verification Starter

Webhook signature verification looks like four lines of crypto.createHmac and is wrong in about six specific ways — verifying a re-serialised body instead of the raw bytes, comparing digests with ===, falling back to GitHub's legacy SHA-1 header, keeping only the first v1= during a Stripe secret rotation, treating Svix's whsec_ secret the way Stripe's is treated, and enforcing a replay window off a timestamp header that isn't inside the signature. This pack has your own coding agent build one verifier for Stripe, GitHub, Shopify and Svix/Resend behind a single function, then proves it against 30 hermetic checks that run offline in under a minute. The execution receipt on this page is the published proof; the better one is the suite itself, which ships in the pack and needs no accounts, no keys and no Docker to run.

Example use cases

• An indie SaaS adding its first Stripe webhook. The endpoint works in stripe listen and 401s the first time a customer with a non-ASCII name pays, because the handler parses the body before verifying and the JSON round-trip is only byte-identical for simple payloads. The raw-body-vs-parsed-body check is that bug, caught before deploy.
• A GitHub App receiving push and pull_request events. The obvious implementation reads whichever signature header is present, which quietly accepts SHA-1. GitHub still sends it "only for legacy purposes"; a verifier that falls back to it has downgraded itself. github-sha1-not-accepted is a four-line fix and a check that stops it coming back.
• A Shopify app developer who copy-pasted a working GitHub verifier. Shopify's digest is base64, GitHub's is hex. Every delivery 401s, the secret looks wrong, and an hour goes into the wrong hypothesis.
• A team on Resend (or Clerk, Brex, Lithic, Loops — anything on Svix) that already has Stripe working. Both secrets start with whsec_. Stripe's is the HMAC key verbatim; Svix's is base64 that must be decoded first. Reusing the Stripe code rejects 100% of genuine deliveries while looking completely reasonable.
• Anyone reviewing someone else's webhook handler. The 30 check names are the review checklist, and running them takes less time than reading the diff.
• Anyone evaluating OneShot. This is a complete pack — same layout, same hermetic verify, same receipt contract as the paid ones — that costs nothing and takes a minute to run.

Why this pack

Honest comparison. This pack is free, so there is no cost saving to claim and none is claimed; what varies between the columns is correctness risk and what you own afterwards.

The six failure modes it pre-solves — specific bug classes, not a claim that every implementation hits every one:

• Verifying a re-serialised body. JSON.parse then JSON.stringify produces different bytes the moment the payload has non-ASCII text, unusual key order or a float. Stripe's own docs list the mutations frameworks apply; Shopify names express.json() explicitly. This is the number-one cause and it is intermittent, which is what makes it expensive.
• Comparing digests with ===. Short-circuits at the first differing byte. GitHub, Stripe and Svix each tell you not to, in those words.
• "Fixing" that with timingSafeEqual and no length guard. It throws RangeError on unequal lengths, and the signature is attacker-controlled — so the security fix converts every malformed signature into an unhandled 500.
• Falling back to a weaker header. GitHub still sends SHA-1. Stripe still sends a v0 test scheme and explicitly says to ignore it.
• Handling one v1 when there can be several. Stripe sends one signature per active secret for up to 24 hours while an endpoint secret rolls. Reading only the first fails roughly half of deliveries during exactly the window you least want an outage.
• Enforcing a replay window that doesn't exist. Shopify sends X-Shopify-Triggered-At and does not sign it, so an attacker replaying a captured delivery just rewrites it. GitHub sends no timestamp at all. The pack records this in data (SCHEMES[p].signedTimestamp) and proves it with a check that forges the header to 1970 and asserts verification still passes.

Scale envelope

Derived from the pinned stack — a node:crypto HMAC and a byte comparison — not from a benchmark. Nothing here is load-tested; the suite proves correctness, not throughput, and ACCEPTANCE.md says so.

• Per request the module does exactly one thing: one HMAC-SHA256 over the body, one constant-time comparison, and for two of the four providers one integer subtraction. No I/O, no allocation beyond the body itself, no shared state, nothing to warm up. It is not the bottleneck in any webhook endpoint, and it does not need to be tuned.
• The realistic bound is your framework's request concurrency, exactly as it was before you added this.
• First ceiling: body size, not rate. Both raw-body helpers buffer the whole body in memory, because an HMAC cannot be checked until the last byte has arrived — that is a property of the construction, not a shortcut. At typical webhook payload sizes (single-digit kilobytes) this is irrelevant. If you receive multi-megabyte bodies, cap the size before buffering, or hash the stream incrementally and compare at the end. Either way, reject oversized bodies at the edge; an unbounded buffer on an unauthenticated endpoint is a denial-of-service surface that no signature check can close.
• Second ceiling — and the real one: there is no second webhook problem solved here. The module has no state, so it scales trivially and stops being the interesting question immediately. The next question is deduplication, and that one needs a database.
• Upgrade path: add a size cap at the edge; add a fifth provider (one file, one entry in two records); then, when duplicates or ordering start mattering, move to a durable pipeline — see below.

What it comfortably covers as shipped: any application receiving webhooks from one to four of these providers, at any volume its own framework can serve. What it isn't: a webhook pipeline. It is the front door.

Verified against

• claude-opus-5
• claude-sonnet-5
• claude-haiku-4-5

Supported stacks

• node-typescript

  node	24.18.1
  typescript	6.0.3
  @types/node	24.3.0
  stripe-api-version	2026-06-24.dahlia
  github-rest-api-version	2022-11-28
  shopify-admin-api-version	2026-07

Estimated buyer token cost

361,000 tokens for one build pass (estimate, not a guarantee).