Stripe's own docs say webhooks arrive twice; code must expect it

The workload

A solo-run SaaS billed through Stripe has to build one more piece of infrastructure beyond checkout: a public HTTPS endpoint that receives Stripe's webhook events and updates the product's database when a payment succeeds, a subscription renews, or a dispute opens. Stripe's documentation on receiving webhook events describes the endpoint's required behavior, verified: accept a POST request with a JSON body, verify it came from Stripe, and return a 2xx response quickly, before anything slow enough to risk a timeout. That is a self-built endpoint, not a paid add-on, though it addresses the double-processing risk this site's own billing research treats as a recurring failure mode.

What the documents show

Stripe's webhook page states, verified, that 'webhook endpoints might occasionally receive the same event more than once,' and instructs a developer to guard against this 'by logging the event IDs you've processed, and then not processing already-logged events' — an idempotency requirement stated directly, not inferred from best practice elsewhere. The same page states, verified, that automatic retries continue for up to three days in live mode, itself a reason duplicate delivery is expected. On authenticity, Stripe's documentation states, verified, that every event carries a signature in a Stripe-Signature header, generated with HMAC-SHA256 using a per-endpoint secret, and a companion page on resolving signature verification errors states, verified, that verification requires three inputs — the raw request body, the header value, and the endpoint's secret — with the raw body flagged, since some frameworks alter it before an application sees it, breaking verification.

The operating cost

Signature verification and deduplication cost engineering time, not a Stripe fee; webhook infrastructure is included with a standard account. The recurring cost is storage and lookup — a table of processed event IDs checked before acting — plus periodic rotation of the signing secret, which Stripe recommends and which briefly runs two active secrets for up to 24 hours during rotation.

The stop condition

Stripe's documentation does not claim its guidance eliminates every billing-state bug; it describes what the endpoint must do, not what outcome that guarantees. This is an editorial stop condition: an endpoint meets the documented minimum once it verifies every request's signature before acting, checks the event ID against a persisted log before processing it twice, and returns a 2xx response before slow logic runs — remaining billing-correctness work is application-specific, outside what these documents cover.

• Does the endpoint verify the Stripe-Signature header before touching the database, on every request, with no exceptions for testing?
• Is there a persisted table of processed event IDs, checked before an event is acted on a second time?
• Does the endpoint return its 2xx response before or after slow downstream work runs?

Stripe's own documentation treats duplicate delivery as a known, expected condition and gives a specific mechanism for handling it. A founder who has not read past the initial handler-setup example may not know the duplicate-handling requirement exists until a customer is charged, or credited, twice.