Guide · by Hamichi

Stripe webhooks: the production gotchas

Updated 21 Nov 2026. Pair this with the Hamichi Webhook Kit if you want tests that fail on these cases on purpose.

Tutorials make Stripe webhooks look like a single POST and a 200 OK. Then you ship, a customer pays, and either nothing happens or something happens twice. Below are the gotchas Hamichi keeps seeing — and that show up in Stripe docs, in Stack Overflow, and in late-night "why is this person still on Pro?" threads.

1. The email is not where you think it is

On a normal Checkout completion, the top-level customer_email field is often null. The address lives on customer_details.email. If your handler does session.customer_email and then bails, you just dropped a paid order. Write a fixture that looks like the live object, not like the tutorial object.

2. If you skip signatures, you do not have a payment system

Stripe signs the raw body with a scheme you can implement yourself: a t= timestamp and a v1= hex HMAC of timestamp + "." + rawBody. Verify that, with a timing-safe compare, before you parse business data. Also reject timestamps outside the usual 300-second window, or anyone with a captured body can replay it later.

Two practical traps: (1) your framework already parsed JSON, so the raw bytes no longer match the signature; (2) you verify against a test secret in production, or the other way around. In NestJS, disable JSON parsing for the webhook route only and read the raw body.

3. Delivery is at least once

Stripe will retry. Your handler will also be retried if you time out or return 5xx. The unique key is event.id. Store it atomically. The second delivery should return 200 and do nothing. "I thought I could just make the grant idempotent" is fine, until two deliveries run at the same moment and both think they are first.

4. Events are not a queue in the order you hoped

customer.subscription.updated can arrive late, or a retry of an older event can land after a newer one. If you blindly set status = event.data.object.status, a late "active" update can resurrect a subscription you already marked canceled. Keep the last applied event.created (or a version you trust) per subscription and ignore stale events. Acknowledge them — do not 500 — so Stripe stops retrying.

5. Success URLs are not a template language

Stripe expands {CHECKOUT_SESSION_ID} and not your own {SESSION_ID} placeholder. The buyer will see the braces. Lint the URL in tests.

6. "Paid" is several events, not one

Checkout, invoices, payment_intent.succeeded, customer.subscription.updated, async payment methods, trials that never convert — these are different stories. A handler that only listens to checkout.session.completed will miss people who started on a trial and later failed a renewal. Your access policy should be a function of stored subscription state, not a side effect of whichever event arrived today. That is what the Hamichi Billing Kit is for.

How to test this without gambling with a live card

The Stripe CLI is the right official tool for sending events at a local URL. It is not a complete regression suite for the cases above. Keep signed fixtures in your repo and run them in CI, with no network. That is the whole point of a webhook kit: the embarrassing cases become red tests, not red customers.

Stack Overflow still has well over a thousand threads that mention Stripe webhooks. The volume is not a reason to panic. It is a reason to stop treating the handler as a 20-line afterthought.