Stripe Webhook Handler

# Spec: Stripe webhook handler

Build POST /api/webhooks/stripe as the single entry point for all Stripe
events, and the only code in this codebase that writes billing state.

## Stack

- Framework: [e.g., Next.js 14 App Router / Express / FastAPI]
- Database: [e.g., Postgres / Supabase / SQLite]

## Environment variables

```bash
STRIPE_SECRET_KEY=sk_test_...
STRIPE_WEBHOOK_SECRET=whsec_...  # `stripe listen` prints one locally;
                                 # production gets its own from the dashboard
```

## Rule 1: verify the signature against the RAW body

- Disable framework body parsing for this route ([Next.js: read the raw
  request body / Express: `express.raw({type: 'application/json'})`]).
  Signature verification hashes the exact bytes; a parsed-then-reserialized
  body fails verification even for legitimate events.
- `stripe.webhooks.constructEvent(rawBody, signatureHeader, secret)`.
  On failure: log it, return 400, write nothing.

## Rule 2: idempotency via a processed-events table

```sql
create table stripe_events (
  id text primary key,            -- Stripe event id (evt_...)
  type text not null,
  processed_at timestamptz not null default now()
);
```

- Insert the event id BEFORE doing work. On primary-key conflict, return 200
  immediately: we have seen this event, the retry is a no-op.
- Every side effect (emails, credits, fulfillment) lives behind this gate.

## Rule 3: explicit event allowlist, 200 for everything else

Handle only the events this app has a handler for. Start with:

- `checkout.session.completed`   -> [fulfill the order / start the subscription]
- `customer.subscription.updated`-> [sync status, price, period end]
- `customer.subscription.deleted`-> [revoke access]
- `invoice.payment_failed`       -> [mark past_due, notify the customer]
- `charge.refunded`              -> [mark the order refunded, revoke if digital]
- `charge.dispute.created`       -> [flag the account, alert a human — no
                                     automated response to disputes]

Unknown types get a 200 and a debug log line. Never a 500: Stripe retries
errors, and a handler that 500s on events it doesn't care about DDoSes
itself with its own backlog.

## Rule 4: the event is a doorbell, not the truth

For subscription and payment state, use the event only to learn WHICH object
changed, then retrieve that object fresh from the API and write from the
response. Events arrive out of order; the API answer is current.

## Structure

```typescript
export async function POST(req: Request) {
  const event = verifyOrThrow(await req.text(), req.headers); // 400 on throw
  if (!(await recordEventOnce(event.id, event.type))) return ok(); // dup
  const handler = handlers[event.type];                // the allowlist
  if (handler) await handler(event);                   // throw -> 500 -> retry
  return ok();                                         // 200 within ~10s
}

const handlers: Record<string, (e: Stripe.Event) => Promise<void>> = {
  "checkout.session.completed": handleCheckoutCompleted,
  "customer.subscription.updated": handleSubscriptionSynced,
  // one small function per event; no billing writes anywhere else
};
```

- Return 200 fast. If a handler needs slow work ([PDF generation / a
  third-party call]), record the event and queue the work; don't make Stripe
  wait on it.
- Throw on real failures (database down) so Stripe retries. Swallowing errors
  and returning 200 deletes the retry and the event is gone for good.

## Verification (before calling this done)

1. `stripe listen --forward-to localhost:3000/api/webhooks/stripe`, then
   `stripe trigger checkout.session.completed`: handler fires, row lands in
   `stripe_events`, the side effect happens once.
2. Resend the same event with `stripe events resend`: 200, zero new side
   effects.
3. POST a hand-forged body with curl and no valid signature: 400, nothing
   written.
4. Trigger an event type not in the allowlist: 200, log line, no writes.