Stripe webhooks

How to Test Stripe Webhooks (and Verify Stripe-Signature)

Stripe tells your application about payments, subscriptions and disputes by sending events to a URL. Before you write the handler, it helps to see exactly what arrives.

Capture a real Stripe webhook in a minute

  1. Get a URL. Use the button on this page. It opens the inspector with a fresh URL that is ready to receive.
  2. Give it to Stripe. In the Stripe Dashboard, open Developers → Webhooks, add an endpoint, paste the URL and choose the events you care about. Use a sandbox or test mode.
  3. Trigger an event. The request appears in the inspector as it arrives, with Stripe recognised and the event name shown.
  4. Check the signature. Open Verify signature, paste your secret and confirm the request is genuine. The check runs in your browser.

What a Stripe webhook looks like

Every event is a POST with a JSON body. The body has an id, a type such as invoice.paid, and the affected object under data.object. One header matters more than the rest:

HeaderMeaning
Stripe-SignatureA timestamp (t=) and one or more signatures (v1=), separated by commas.
Content-Typeapplication/json
User-AgentIdentifies Stripe. Do not rely on it for authentication.

How the signature is computed

Stripe builds a string from the timestamp, a full stop and the raw request body, then computes an HMAC-SHA256 of it using your endpoint's signing secret (it starts with whsec_). The result, in hex, is the v1 value.

Verifying Stripe-Signature by hand (Node.js)
import crypto from "node:crypto";

export function verifyStripe(rawBody, header, secret, toleranceSeconds = 300) {
  const pairs = header.split(",").map((part) => part.split("="));
  const timestamp = pairs.find(([k]) => k === "t")?.[1];
  const signatures = pairs.filter(([k]) => k === "v1").map(([, v]) => v);

  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${timestamp}.${rawBody}`)
    .digest("hex");

  const fresh = Math.abs(Date.now() / 1000 - Number(timestamp)) <= toleranceSeconds;
  return fresh && signatures.some(
    (s) => s.length === expected.length &&
      crypto.timingSafeEqual(Buffer.from(s), Buffer.from(expected))
  );
}

In production, prefer the official library: stripe.webhooks.constructEvent(rawBody, signature, secret) does the same thing and throws when the check fails.

The mistake that costs an afternoonThe signature covers the raw bytes. If your framework parses the JSON and you re-serialise it, key order and whitespace change and verification fails. Read the raw body for the webhook route before any JSON middleware touches it.

What Stripe expects back

  • A 2xx status, quickly. Acknowledge first, then do slow work in the background. Anything else counts as a failure.
  • Retries. In live mode Stripe retries failed deliveries with exponential backoff for up to three days. Sandboxes retry a few times over a few hours.
  • Duplicates and ordering. The same event can arrive more than once and events can arrive out of order. Record processed event IDs and make handlers idempotent.

To see how your code copes with a failing endpoint, set a custom response on your webhook.stream URL (for example a 500) and watch Stripe retry.

Triggering test events

The Stripe CLI can fire events on demand, which is faster than clicking through a checkout:

Stripe CLI
stripe trigger payment_intent.succeeded
stripe trigger invoice.paid
stripe trigger customer.subscription.deleted

Events triggered this way are delivered to the webhook endpoints registered on the account, including your webhook.stream URL.

Frequently asked questions

Why does my Stripe signature verification fail?

Almost always because the body was changed before verification: parsed and re-serialised JSON, a trimmed newline or a different character encoding. Verify against the raw bytes. The second most common cause is using the wrong secret: each endpoint has its own signing secret, and the Stripe CLI uses a different one from the Dashboard.

Does Stripe retry failed webhooks?

Yes. In live mode Stripe retries with exponential backoff for up to three days. Design handlers so that receiving the same event twice is harmless.

Can I test Stripe webhooks without deploying my server?

Yes. Point Stripe at a webhook.stream URL to see the real payloads, then use the stream API to forward them to a server running on localhost.