Webhook signature: definition, how HMAC verification works and what breaks it

A webhook signature proves an event came from your provider unchanged. How HMAC-SHA256 verification works, and what Stripe, Polar and Dodo Payments sign.

Definition

A webhook signature is a code the sender computes from the request body and a shared secret, usually with HMAC-SHA256, and sends in a header. The receiver recomputes it from the raw body; if the two match, the event came from the provider and nobody changed it. A signed timestamp also lets the receiver reject replayed events.

  • Verify against the raw request body; parsing and re-serializing the JSON changes the bytes and breaks the check.
  • A signing secret can confirm events but cannot call the provider's API, so it is far less dangerous to share than an API key.

A webhook signature proves that an event really came from your payment provider and that nobody changed it on the way. When Stripe tells your server a checkout completed, it sends a Stripe-Signature header with a timestamp and an HMAC-SHA256 of the timestamp plus the raw body, keyed with your endpoint's whsec_ secret (Stripe).

How it works

The provider and your server share a secret. For each event the provider signs a defined string, and your server repeats the calculation:

  1. Read the raw request body, before any JSON parsing.
  2. Build the signed string exactly as the provider defines it.
  3. Compute HMAC-SHA256 with the signing secret.
  4. Compare your result with the header in constant time.
  5. Reject the event if its timestamp is too old. Stripe's libraries default to a 5-minute tolerance.
ProviderSignature headerWhat is signed
StripeStripe-Signature (t=…,v1=…){t}.{raw body}
Polarwebhook-signature, with webhook-id and webhook-timestamp{id}.{timestamp}.{body} (Standard Webhooks)
Dodo Paymentswebhook-signature (v1,<base64>), with the same two headers{id}.{timestamp}.{body}
Lemon SqueezyX-Signaturethe raw body only

Lemon Squeezy's signature has no timestamp, so replay protection is up to you: record the order IDs you have already processed and skip repeats. Lemon Squeezy also stops processing transactions on March 31, 2027, so plan the move to another provider's scheme (Lemon Squeezy migration).

A minimal Stripe check looks like this. In production, prefer the provider's library, such as stripe.webhooks.constructEvent in Stripe's Node SDK.

verify-stripe-signature.ts
import { createHmac, timingSafeEqual } from "node:crypto";

export function verifyStripeSignature(
  rawBody: string,
  header: string,
  secret: string,
  toleranceSeconds = 300,
): boolean {
  const pairs = header.split(",").map((part) => part.split("=", 2));
  const timestamp = pairs.find(([key]) => key === "t")?.[1];
  const signatures = pairs.filter(([key]) => key === "v1").map(([, value]) => value ?? "");
  if (!timestamp || signatures.length === 0) return false;

  const age = Math.abs(Date.now() / 1000 - Number(timestamp));
  if (!Number.isFinite(age) || age > toleranceSeconds) return false;

  const expected = Buffer.from(createHmac("sha256", secret).update(`${timestamp}.${rawBody}`).digest("hex"));
  return signatures.some((signature) => {
    const received = Buffer.from(signature);
    return received.length === expected.length && timingSafeEqual(received, expected);
  });
}

Why it matters for pricing

Revenue numbers in a price test are only as good as the events behind them. An endpoint that skips the check accepts any POST that looks like a payment, so a single fake event can make a losing price look like the winner.

This is why Leverprice asks for your webhook signing secret: a signing secret can confirm events but cannot move money, and revenue that does not arrive in a verified provider event is labeled unverified (verified revenue).

Common mistakes

  • Verifying a parsed and re-serialized body. Frameworks that parse JSON first change the bytes, so read the raw body, for example with await request.text() in a fetch-style handler.
  • Comparing signatures with ===, which can leak timing information. Use a constant-time comparison.
  • Skipping the timestamp check, which lets an attacker replay an old, validly signed event.
  • Mixing test-mode and live-mode secrets, which makes every live event fail verification.

Verified purchases are what make revenue per visitor trustworthy in a price test. Polar, Lemon Squeezy and Dodo Payments each act as a merchant of record and sign their webhooks too, and payment processing fees are what the provider keeps from each verified payment.

Frequently asked questions

Is a webhook signing secret the same as an API key?

No. An API key can call the provider's API, including refunds and payouts, while a signing secret can only prove that an event is genuine.

What should my endpoint do when verification fails?

Return an error status and log the attempt without processing the event. Stripe retries live-mode deliveries for up to three days, so a genuine event that failed because of a bug can still arrive after you fix it (Stripe).

Why does my signature check fail even with the right secret?

Most often the body was parsed before you verified it, or a proxy changed it. Verify against the exact bytes the provider sent, and check that you are using the secret for the right endpoint and mode.