TechnicalFix a Stripe webhook that never arrives or keeps failing
Act as a senior payments engineer. In my {{tech_stack}} app, customers pay through Stripe but orders are never marked paid, or the webhook shows errors. What I see: {{error_message}}
Gather evidence first:
- In the Stripe dashboard's webhooks section: is this endpoint listed in the right mode (test or live), subscribed to the right events, and what status and response body did recent deliveries get?
- The server or function logs at the moment of delivery
- Locally, forward events with the Stripe CLI and trigger a test event to reproduce it
Likely causes, ranked for this symptom:
1. Signature verification fails because the body was parsed as JSON first; verification needs the raw request body
2. The wrong signing secret: the test secret in live mode, the CLI's secret in production, or an old secret after the endpoint was recreated
3. Never arrives: wrong endpoint URL, a redirect (http to https, or www), or middleware that demands a signed-in session
4. Not subscribed to the event the code waits for, such as checkout.session.completed versus payment_intent.succeeded
5. Timeouts: slow work before responding, so Stripe retries and the order is processed twice
6. The handler throws on a field missing from some events, such as a metadata key
Confirm the cause from the delivery log and server logs, then fix the smallest thing. Rules: keep signature verification, always; return a 2xx quickly and do slow work after; make the handler idempotent by storing event ids, so retries never fulfill twice; take amounts from Stripe's data, never the browser. Add a test that sends a signed test event twice and checks the order updates once. Explain what was wrong in plain words, and how to resend failed events.