Stripe webhook testing: events, signatures and failures

Stripe sends each event as a signed JSON POST and retries for days when your endpoint fails. Testing a Stripe integration means checking three things: the signature check passes on real deliveries (and only on them), your handler survives duplicates and out-of-order events, and it answers fast enough that Stripe doesn't retry.
Get a free webhook URL Free, no account needed.

By the HookWatcher team · Updated

What a Stripe delivery looks like

An event is a POST to your endpoint URL with the Event object as the body and a Stripe-Signature header. Stripe documents only that header; capture a real delivery to see every header your account receives.

A payment_intent.succeeded delivery (body in Stripe's Event format; values are examples)
POST /webhooks/stripe HTTP/1.1
Host: example.com
Content-Type: application/json
Stripe-Signature: t=1763190000,v1=c82deb382459ce30429c893a997e56affc75d68c9db8989c90d9b7bd7d4fc05a

{
  "id": "evt_3QabCdEfGh1234567",
  "object": "event",
  "api_version": "2024-06-20",
  "created": 1763189998,
  "data": {
    "object": {
      "id": "pi_3QabCdEfGh1234567",
      "object": "payment_intent",
      "amount": 4999,
      "amount_received": 4999,
      "currency": "usd",
      "status": "succeeded",
      "metadata": {
        "order_id": "ord_1042"
      }
    }
  },
  "livemode": false,
  "pending_webhooks": 1,
  "request": {
    "id": "req_8xYzAbCdEf",
    "idempotency_key": "5f0b1c1e-2d3a-4b5c-9d8e-7f6a5b4c3d2e"
  },
  "type": "payment_intent.succeeded"
}

The signature is real: it's HMAC-SHA256 over 1763190000. followed by the body exactly as shown, with the example secret whsec_test_51HookWatcherExample. Paste them into the signature generator (format Stripe, timestamp 1763190000) to get the same value. Because the timestamp is in the past, a library with the default tolerance rejects it, which is the point of the timestamp.

The header, part by part

  • t: Unix seconds when Stripe signed the request. It's part of the signed string, so it can't be changed without breaking the signature.
  • v1: the HMAC-SHA256 signature. There can be several v1 entries while you roll an endpoint's secret (Stripe keeps the previous secret valid for up to 7 days); accept the request if any matches.
  • v0: appears on sandbox events and must be ignored. Only check v1, so an attacker can't downgrade to another scheme.

Event fields that matter in a handler

Stripe Event object fields
FieldUse it forWatch out for
idDeduplication: record processed evt_ IDsThe same event can be delivered more than once
typeRouting to the right handlerAcknowledge types you don't handle with a 2xx
data.objectThe object (PaymentIntent, Invoice…) as of the eventIt's a snapshot; fetch the object from the API if you need its current state
createdLoggingSeconds only: distinct events can share it. Stripe says not to use it for ordering
livemodeRefusing sandbox events in production (and the reverse)Test and live endpoints have different secrets
api_versionKnowing which shape data.object hasPayloads change when the version changes
requestTracing an event to the API call that caused it (id, idempotency_key)Null for events not caused by an API request
pending_webhooksDebugging delivery backlogsCounts undelivered endpoints, not retries

Updates such as customer.updated also include data.previous_attributes with the fields that changed.

Ways to send test events

Sending Stripe test events
MethodCommand or placeGood for
Stripe CLI to localhoststripe listen --events payment_intent.succeeded --forward-to localhost:4242/webhooks/stripeDevelopment on your machine. The CLI prints its own whsec_ secret, different from the Dashboard endpoint's
Trigger an eventstripe trigger payment_intent.succeededCreating real sandbox objects and their events (it also fires related events, such as payment_intent.created)
Resend a past eventstripe events resend evt_… --webhook-endpoint=we_… (up to 30 days), or Resend in the Dashboard (up to 15 days)Reproducing a failure with the original event
Capture with HookWatcherPoint a Dashboard endpoint at a HookWatcher URL, then deliver or replay to localhostSeeing exactly what Stripe sent, and replaying it with a fresh signature (hwcli replay --resign) after the original timestamp has expired

Verify Stripe-Signature

Use Stripe's library where you can. The two requirements are the exact raw body and the secret of this endpoint in this mode:

Node.js (Express), Stripe's documented pattern
// npm install stripe express
const express = require("express");
const stripe = require("stripe")(process.env.STRIPE_SECRET_KEY);
const endpointSecret = process.env.STRIPE_WEBHOOK_SECRET; // whsec_… for THIS endpoint and mode

const app = express();

// The raw body route must come before app.use(express.json()).
app.post("/webhooks/stripe", express.raw({ type: "application/json" }), (req, res) => {
  let event;
  try {
    event = stripe.webhooks.constructEvent(req.body, req.headers["stripe-signature"], endpointSecret);
  } catch (err) {
    return res.status(400).send(`Webhook Error: ${err.message}`);
  }

  // Acknowledge fast; do the work in a queue. Deduplicate on event.id.
  enqueue(event.id, event.type, event.data.object);
  res.json({ received: true });
});

app.use(express.json()); // other routes

Without a library, verification is short. This Python function implements Stripe's documented steps; it is tested against the example delivery above:

Python, standard library only
import hashlib
import hmac
import time


def verify_stripe(payload: bytes, header: str, secret: str, tolerance: int = 300) -> bool:
    """Stripe-Signature check: HMAC-SHA256 of "t.payload"; only v1 entries count."""
    items = [part.split("=", 1) for part in header.split(",") if "=" in part]
    timestamps = [value for key, value in items if key.strip() == "t"]
    signatures = [value for key, value in items if key.strip() == "v1"]
    if len(timestamps) != 1 or not (timestamps[0].isascii() and timestamps[0].isdigit()) or not signatures:
        return False
    signed = timestamps[0].encode() + b"." + payload
    expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
    # Compare bytes: compare_digest raises on non-ASCII str, and the header is attacker-controlled.
    if not any(hmac.compare_digest(expected.encode(), sig.encode()) for sig in signatures):
        return False
    return abs(time.time() - int(timestamps[0])) <= tolerance

Try it live

Try it: verify Stripe deliveries

Live, on a real endpoint
Three Stripe-format deliveries to a real endpoint: one your handler should accept and two it must reject.
No account. The endpoint is yours in this browser and also opens in the playground.

Troubleshooting

Stripe webhook problems and fixes
SymptomCauseFix
"No signatures found matching the expected signature for payload"Wrong secret (the most common cause, per Stripe), a body your framework parsed or changed, or whitespace copied into the secretUse the secret of this endpoint and mode; verify over the raw body (express.raw before express.json); trim the secret
Signature fails only with the Stripe CLIThe CLI's forwarding secret differs from the Dashboard endpoint'sUse the whsec_ the CLI prints; it doesn't change between restarts
Timestamp outside the toleranceServer clock drift, or a captured request sent again laterSync the clock with NTP; replay with a fresh signature instead of resending old bytes. Never set the tolerance to 0 (that disables the check)
Deliveries fail with a 3xxStripe treats redirects as failures (http → https, trailing slash, www)Set the endpoint to the final URL the redirect points to
No deliveries at allEvent type not selected, sandbox vs live endpoint, endpoint disabledCheck the endpoint's event list and mode in the Dashboard; send a test event to a capture URL to separate Stripe from your server
The same event processed twiceDuplicate deliveries, or a retry after a slow responseRecord event.id atomically and skip seen IDs; respond 2xx before slow work
Two events for one changeStripe can generate separate Event objects for one changeDetect them with data.object.id plus type
Events in the wrong orderStripe doesn't guarantee orderMake handlers tolerate it: check the object's current state via the API instead of assuming a sequence
Retries keep coming after a fixLive mode retries for up to three days with exponential backoff (sandbox: three times over a few hours); a manual resend doesn't cancel themAnswer the retries with a 2xx once fixed; they stop when one succeeds

Allowlisting IPs? Stripe publishes the addresses it sends webhooks from on its IP addresses page, with notice before changes. Keep verifying signatures either way.

Inspect your Stripe webhook payload

Add a free HookWatcher URL as an endpoint in Stripe's Dashboard, send a test event and see the exact body and Stripe-Signature header it delivered. HookWatcher labels it as Stripe with its event type.
Get a free webhook URL No account or card needed. Want to keep it? Create a free account

Frequently asked questions

Can I test Stripe webhooks without the Stripe CLI?

Yes. Add a public URL (such as a HookWatcher endpoint) in the Dashboard and send or resend events to it. Use the CLI when you want events forwarded straight to localhost or want to trigger new sandbox events.

Why does a replayed Stripe event fail verification?

The signature covers the timestamp, and libraries reject timestamps older than five minutes by default. Resending old bytes later fails by design. Replay with a fresh signature (hwcli replay <event> --resign with the endpoint's secret stored in HookWatcher), or have Stripe resend the event.

Do test and live mode share a signing secret?

No. Each endpoint has its own secret, an endpoint used for both test and live keys has a different secret for each, and the CLI's forwarding secret is different again. All start with whsec_.

Does HookWatcher verify Stripe signatures?

On paid plans, yes: save the endpoint's signing secret and each capture is checked against the exact bytes received, including the five-minute tolerance at capture time. The secret is stored encrypted and never shown again.

What should my endpoint return?

A 2xx as soon as the event is verified and stored, before slow work. Stripe treats other statuses, redirects and slow responses as failures and retries.

Sources