Stripe Webhook Security: 12 Patterns That Survive Production

Stripe webhooks are how the money state machine in your application stays consistent with the money state machine at Stripe. Every subscription created, every payment failure, every refund, every dispute — they all arrive as webhooks. Get this wrong and you have double-charges, missing entitlements, ghost subscriptions, and angry support emails.

We ship Stripe integrations as a core service at QUANT LAB USA. These twelve patterns are the production handbook. See also our Next.js + Stripe integration guide and our Stripe Connect Marketplace Architecture.

1. Verify signatures with the raw request body
2. Enforce timestamp tolerance for replay protection
3. Persist every event ID for deduplication
4. Acknowledge fast, process async
5. Idempotency keys on every downstream side effect
6. Subscribe only to events you handle
7. Return 2xx for unhandled event types
8. Queue-based processing with a durable worker
9. Dead-letter queue for permanent failures
10. Rotate signing secrets through dual-secret windows
11. Monitor delivery success rate as an SLO
12. Replay missed events from the dashboard

Stripe signs the exact bytes it sent. JSON parsing reorders keys and normalizes whitespace, which changes the byte sequence. Read the body as a string or ArrayBuffer first, verify, then parse.

In Next.js App Router, the route handler must call request.text() before any JSON parsing. Use stripe.webhooks.constructEvent(rawBody, signature, secret) — never roll your own HMAC. The Stripe SDK handles signature scheme version (v1) and timestamp parsing.

Signing secrets begin with whsec_. Store in environment variables. Never log them.

Stripe's signed payload includes a Unix timestamp. The SDK rejects anything older than 5 minutes by default. This prevents an attacker who captures a valid webhook from replaying it weeks later.

Default tolerance is fine for most workloads. Tighten it (60 seconds) for high-value flows; loosen it (10 minutes) only if you operate in a degraded clock-skew environment.

Stripe will sometimes re-deliver the same event legitimately — even after you returned 200. Maintain a database table of processed event IDs and reject duplicates at the handler entry point.

Use the event's id field (which starts with evt_) as the primary key. Add a unique constraint and catch the integrity violation. Retention can be capped at 30 days — older replays are unusual and Stripe documents the cap as 3 days.

Stripe's webhook delivery timeout is 30 seconds. Anything slower retries. Inline processing — sending emails, calling third-party APIs, running database transactions — risks timeouts and double-execution.

The pattern: verify, persist the event to a durable queue (BullMQ, SQS, Inngest, Trigger.dev), return 200. The worker processes the event asynchronously. If the worker fails, the queue handles retry without Stripe re-delivering.

Target inline ack time: under 200ms P95. We monitor this as an SLO.

Every downstream side effect — sending email, calling external API, writing to your database, triggering a fulfillment job — must be idempotent. The same event arriving twice should produce the same observable outcome.

Pattern: use the Stripe event ID as the idempotency key for downstream API calls (Stripe APIs natively support an Idempotency-Key header). For internal mutations, use unique constraints and ON CONFLICT DO NOTHING. For email, dedupe by event_id + recipient.

Stripe lets you enable all events or specific event types per endpoint. Subscribe only to what your handler implements. Reduces noise, reduces handler logic surface area, and reduces the risk that a new Stripe event type triggers behavior you did not intend.

Common event types for SaaS: customer.subscription.created, customer.subscription.updated, customer.subscription.deleted, invoice.paid, invoice.payment_failed, customer.subscription.trial_will_end, checkout.session.completed.

If an event arrives that your code does not handle, return 200, not 4xx. Returning 4xx signals "permanent failure" but Stripe will still retry for a while, and you will spam your error logs and alerting.

Pattern: log the unknown event type at info level for visibility, then return 200. Add a handler when you actually want to act on it.

The webhook handler enqueues. A separate worker process consumes. The worker has its own retry policy, its own scaling profile, and its own dead-letter behavior.

Our default stack: Inngest or Trigger.dev for managed; BullMQ on Redis for self-hosted. For higher-volume customers, SQS + Lambda. Each event becomes a job with the Stripe event ID as the deduplication key.

Jobs that fail after all retries land in a dead-letter queue. A human reviews them, fixes the root cause, and replays. Without this, a transient bug becomes silent data drift.

Alert on any item in the DLQ. The bar for "you should know about this" is low — these are events your money state machine could not absorb.

Stripe lets you add a second active signing secret to the same endpoint during rotation. The pattern:

1. Generate a new signing secret in Stripe dashboard.
2. Deploy code that tries the new secret first, falls back to old secret. Both signing keys verify.
3. Wait 24 hours to confirm new secret is in use and stable.
4. Delete the old secret in Stripe dashboard.
5. Deploy code that only uses the new secret.

The Stripe dashboard surfaces delivery success rate per endpoint. Alert when it drops below 99%. Alongside that, monitor:

• P95 ack latency (target under 200ms)
• Worker processing latency (target under 30s)
• DLQ depth (target zero)
• Duplicate event rejections per day (informational)
• Unhandled event types per week (capture for triage)

When an outage causes Stripe to give up retrying, the Stripe dashboard lets you replay individual events or a time-window batch. Document the replay process in your runbook. Test it in staging at least once a year.

For very large replay windows, ask Stripe support for a bulk export — they can ship you a JSONL file of events for a date range that your worker can ingest offline.

1. Unit tests: Mock Stripe SDK, fixture event payloads, assert handler side effects.
2. Integration tests: Use Stripe CLI stripe trigger against a test Stripe account.
3. Pre-prod tests: Mirror production webhook config in a sandbox; run full E2E flows.

For PCI considerations around webhooks, see our PCI-DSS Compliance for SaaS Checklist.