Instructions

Implement webhook receivers in Next.js Route Handlers. For payment events, also follow payments-pci.md.

When to Use

• Use when adding Stripe/GitHub/PSP (or similar) HTTP callbacks.
• Prefer payments-handbook for PCI/checkout architecture; this skill owns verify + idempotency + status codes.
• Prefer api-handbook for the internal APIs the webhook calls after verify.

1. Verify signatures using provider docs - use crypto.timingSafeEqual (or equivalent) on decoded buffers for HMAC; never === on user-controlled strings.
2. Raw body: read bytes before JSON parse when the signature covers the raw body.
3. Idempotency: store event id or dedupe key; return 200 if already processed.
4. Timeouts: respond quickly; queue heavy work to a background job pattern the user owns.
5. Replay: timestamp tolerance ± a few minutes; reject stale events.
6. Status matrix: 2xx = stop retries; 4xx for permanent bad signatures; 5xx only when the provider should retry.

Outcomes