Stripe webhook testing: events, signatures and failures
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.
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 severalv1entries 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 checkv1, so an attacker can't downgrade to another scheme.
Event fields that matter in a handler
| Field | Use it for | Watch out for |
|---|---|---|
id | Deduplication: record processed evt_ IDs | The same event can be delivered more than once |
type | Routing to the right handler | Acknowledge types you don't handle with a 2xx |
data.object | The object (PaymentIntent, Invoice…) as of the event | It's a snapshot; fetch the object from the API if you need its current state |
created | Logging | Seconds only: distinct events can share it. Stripe says not to use it for ordering |
livemode | Refusing sandbox events in production (and the reverse) | Test and live endpoints have different secrets |
api_version | Knowing which shape data.object has | Payloads change when the version changes |
request | Tracing an event to the API call that caused it (id, idempotency_key) | Null for events not caused by an API request |
pending_webhooks | Debugging delivery backlogs | Counts undelivered endpoints, not retries |
Updates such as customer.updated also include data.previous_attributes with the fields that changed.
Ways to send test events
| Method | Command or place | Good for |
|---|---|---|
| Stripe CLI to localhost | stripe listen --events payment_intent.succeeded --forward-to localhost:4242/webhooks/stripe | Development on your machine. The CLI prints its own whsec_ secret, different from the Dashboard endpoint's |
| Trigger an event | stripe trigger payment_intent.succeeded | Creating real sandbox objects and their events (it also fires related events, such as payment_intent.created) |
| Resend a past event | stripe 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 HookWatcher | Point a Dashboard endpoint at a HookWatcher URL, then deliver or replay to localhost | Seeing 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:
// 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 routesWithout a library, verification is short. This Python function implements Stripe's documented steps; it is tested against the example delivery above:
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])) <= toleranceTry it live
Try it: verify Stripe deliveries
Live, on a real endpointTroubleshooting
| Symptom | Cause | Fix |
|---|---|---|
| "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 secret | Use 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 CLI | The CLI's forwarding secret differs from the Dashboard endpoint's | Use the whsec_ the CLI prints; it doesn't change between restarts |
| Timestamp outside the tolerance | Server clock drift, or a captured request sent again later | Sync 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 3xx | Stripe treats redirects as failures (http → https, trailing slash, www) | Set the endpoint to the final URL the redirect points to |
| No deliveries at all | Event type not selected, sandbox vs live endpoint, endpoint disabled | Check 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 twice | Duplicate deliveries, or a retry after a slow response | Record event.id atomically and skip seen IDs; respond 2xx before slow work |
| Two events for one change | Stripe can generate separate Event objects for one change | Detect them with data.object.id plus type |
| Events in the wrong order | Stripe doesn't guarantee order | Make handlers tolerate it: check the object's current state via the API instead of assuming a sequence |
| Retries keep coming after a fix | Live mode retries for up to three days with exponential backoff (sandbox: three times over a few hours); a manual resend doesn't cancel them | Answer 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
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
- Stripe Docs: Receive Stripe events in your webhook endpoint (signatures, retries, ordering)
- Stripe Docs: Verify signatures manually
- Stripe Docs: Resolve webhook signature verification errors
- Stripe API: The Event object
- Stripe CLI: stripe listen
- Stripe CLI: stripe trigger
- Stripe CLI: stripe events resend
- Stripe Docs: IP addresses