# Stripe Webhooks

Webhook discipline for Stripe event handling.

## Rules

1. **Verify signatures on every request.** Use `stripe.webhooks.constructEvent` with your endpoint secret. Unverified webhooks are unsigned POSTs anyone can forge.

2. **Handle events idempotently.** Stripe retries webhooks. Store processed event IDs and skip duplicates. Double-processing `checkout.session.completed` double-fulfills orders.

3. **Return 200 fast, process async.** Acknowledge within Stripe's timeout. Heavy work — emails, provisioning, fulfillment — belongs in a queue, not the webhook handler.

4. **Subscribe to events you handle.** Don't listen to everything. Each handler maps to explicit event types. Unhandled events are logged, not errors.

5. **Test with Stripe CLI.** `stripe listen --forward-to` and fixture events before production. Don't discover handler bugs from live customer payments.

## What This Replaces

Unverified webhook endpoints, synchronous fulfillment in the HTTP handler, and double-processing on Stripe retries.

## Official Source

Distilled from Stripe's official agent skills.
Full upstream: https://officialskills.sh/stripe/skills/stripe-best-practices