void-webhook-handler-pattern

Create a route at app/api/webhooks/stripe/route.ts that reads the raw body, verifies the stripe-signature header with stripe.webhooks.constructEvent, deduplicates on event.id in an inbox table, validates with Zod, then dispatches to a service. Return 2xx on success and 5xx only for retryable failures.

Insert the source's unique event identifier (Stripe event.id, svix-id, or x-github-delivery) into a webhook_inbox table with a unique key constraint before processing. If the insert conflicts, the event was already handled, so return 2xx immediately to stop sender retries.

Return 2xx for accepted events, 401 for invalid signatures, 4xx for permanent failures like malformed payloads (logged to a dead-letter queue), and 5xx only for transient errors. Never return 200 to a malformed event, since that silently accepts invalid data.

No, GitHub does not auto-retry webhooks, so a 5xx response means the event is lost. Stripe retries with exponential backoff for up to 3 days, and Svix (Resend) retries automatically, so dead-letter routing matters most for GitHub endpoints.

timingSafeEqual performs a constant-time comparison that prevents timing attacks, where an attacker measures response times to guess a valid signature byte by byte. Using == for HMAC comparison exits early on the first mismatched byte and leaks that information.