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:
- Read the raw request body, before any JSON parsing.
- Build the signed string exactly as the provider defines it.
- Compute HMAC-SHA256 with the signing secret.
- Compare your result with the header in constant time.
- Reject the event if its timestamp is too old. Stripe's libraries default to a 5-minute tolerance.
| Provider | Signature header | What is signed |
|---|---|---|
| Stripe | Stripe-Signature (t=…,v1=…) | {t}.{raw body} |
| Polar | webhook-signature, with webhook-id and webhook-timestamp | {id}.{timestamp}.{body} (Standard Webhooks) |
| Dodo Payments | webhook-signature (v1,<base64>), with the same two headers | {id}.{timestamp}.{body} |
| Lemon Squeezy | X-Signature | the 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.
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.
Related terms
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.