Webhooks that handle every event reliably, including duplicates and failures.

Webhook handling has specific requirements:

Signature verification:

// Stripe example
const event = stripe.webhooks.constructEvent(
  rawBody,
  req.headers['stripe-signature'],
  process.env.STRIPE_WEBHOOK_SECRET
);

Every webhook provider sends a signature header. Verify it before processing the event. Without verification: anyone can send fake events to your endpoint.

Idempotent processing: Stripe guarantees at-least-once delivery. The same event can arrive multiple times. Processing must be idempotent: check if the event ID has been processed already before acting.

const existing = await db.query.webhookEvents.findFirst({
  where: eq(webhookEvents.eventId, event.id)
});
if (existing) return; // Already processed

Respond immediately, process async: Webhook providers expect a 200 response within seconds. Long processing (sending emails, updating database, calling other APIs) must happen async. Respond 200 immediately; queue the work.

Retry handling: Stripe retries on non-2xx responses. Log the event and return 200 even if processing fails; handle errors in the background worker.

Out-of-order events: Events don't always arrive in the order they were sent. A payment_intent.succeeded might arrive before checkout.session.completed. Process based on the event's data, not assumed ordering.