Webhook Receiver

# Project: Webhook receiver for [provider]

Build an endpoint that receives [provider] webhooks for the events
listed below. The receive/verify/dedupe skeleton is fixed; only the
per-event processing is custom.

## Events to handle

- `[event.type.one]`: [what we do: e.g., mark the order paid]
- `[event.type.two]`: [what we do]
- Any other event type: verify, store, return 200, do nothing. An
  unknown event is never an error; providers add types without asking.

## The skeleton (order is load-bearing)

```
receive -> verify signature -> insert event id -> return 200 -> process
```

1. Read the RAW request body bytes. Verification signs the exact
   bytes sent; a parsed-then-reserialized body will not match.
2. Verify the signature using `[PROVIDER]_WEBHOOK_SECRET` from the
   environment. Use the provider's official verification helper if
   the SDK has one; otherwise HMAC-SHA256 over the raw body with a
   timing-safe comparison, and reject timestamps older than 5
   minutes to block replays. Failure: 401, log, stop. No partial
   trust: an unverified payload is not data, it is input from a
   stranger.
3. Extract the provider's event ID and insert into `webhook_events`.
   Unique-violation on insert means we have seen this delivery:
   return 200 immediately and do NOT process again. That 200 is
   correct. It tells the provider to stop retrying.
4. Return 200 now, before processing. Target under 1 second.
5. Process the event after the response (queue, background function,
   or a worker polling the table; pick per platform. On serverless
   a dangling promise is NOT "after", the runtime freezes it).

## Events table

```sql
CREATE TABLE webhook_events (
  id           TEXT PRIMARY KEY,        -- provider's event id
  event_type   TEXT NOT NULL,
  payload      JSONB NOT NULL,          -- full raw event, always
  received_at  TIMESTAMPTZ NOT NULL DEFAULT now(),
  processed_at TIMESTAMPTZ,             -- null until work completes
  attempts     INT NOT NULL DEFAULT 0,
  last_error   TEXT
);
```

Storing the full payload means a processing bug is recoverable: fix
the code, reprocess the stored rows, nothing lost.

## Handler sketch

```typescript
export async function POST(req: Request) {
  const raw = await req.text();
  if (!verifySignature(raw, req.headers)) {
    return new Response("bad signature", { status: 401 });
  }
  const event = JSON.parse(raw);
  const inserted = await db.insertIgnoreDuplicate("webhook_events", {
    id: event.id, event_type: event.type, payload: event,
  });
  if (!inserted) return new Response("ok", { status: 200 }); // duplicate
  await enqueueProcessing(event.id); // hand off; do not await the work
  return new Response("ok", { status: 200 });
}
```

## Processing rules

- Each processor loads the payload from `webhook_events` by id, does
  its work, sets `processed_at`.
- Processors must be idempotent anyway (use UPDATE-where-not-already
  / upserts), because "exactly once" is a direction, not a guarantee.
- On processing failure: increment `attempts`, record `last_error`,
  retry with backoff up to 5 attempts, then leave the row unprocessed
  and alert me ([how: Slack message, email]). Never retry forever.
- Ordering is not guaranteed. Events can arrive late, out of order,
  or twice; processors decide from CURRENT stored state, not from
  assumed sequence.

## Configuration

- Env vars: `[PROVIDER]_WEBHOOK_SECRET`, `DATABASE_URL`. Provide
  `.env.example`. The secret never appears in code or logs.
- Log every received event: id, type, verified yes/no, duplicate
  yes/no. Never log the secret or full payloads of sensitive events.

## Done means (test each one, not just the happy path)

- Valid event: 200, one row, processed once.
- Same event delivered twice: 200 both times, ONE row, processed once.
- Tampered body with real headers: 401, zero rows.
- Unknown event type: 200, row stored, no processor invoked.
- Processor throws: response was already 200, `attempts` increments,
  retry happens, `last_error` is readable.