Webhook Integration Guide: Receive, Verify & Process Events Reliably

Step 1 — Always verify the signature

Every serious webhook provider signs its payloads with an HMAC-SHA256 signature. Your receiver must verify this before doing anything else — an unverified handler is an open door for replay attacks and forged events.

1import Stripe from "stripe";2const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!);3 4export async function POST(req: Request) {5  const body = await req.text(); // raw body — required for signature check6  const sig = req.headers.get("stripe-signature")!;7  let event: Stripe.Event;8  try {9    event = stripe.webhooks.constructEvent(body, sig, process.env.STRIPE_WEBHOOK_SECRET!);10  } catch {11    return new Response("Bad signature", { status: 400 });12  }13  await queue.add("stripe-event", event); // hand off immediately14  return new Response("ok");15}

Step 2 — Respond fast, process async

Webhook providers (Stripe, GitHub, etc.) expect a 2xx response within 5–30 seconds or they retry. Heavy processing — sending emails, updating databases, calling other APIs — should happen in a background queue, not in the handler itself.

Step 3 — Idempotent processing

Every webhook can be delivered more than once (network blips, provider retries). Your processor must be idempotent — running it twice on the same event must have the same result as running it once. The simplest pattern: store the event ID and skip if already seen.

1export async function handleStripeEvent(event: Stripe.Event) {2  const exists = await db.processedEvent.findUnique({ where: { id: event.id } });3  if (exists) return; // already handled — safe to skip4 5  await db.processedEvent.create({ data: { id: event.id } });6 7  if (event.type === "checkout.session.completed") {8    const session = event.data.object as Stripe.Checkout.Session;9    await activateSubscription(session.metadata!.orgId);10  }11}

Step 4 — Handle retries gracefully

When your handler returns a non-2xx, providers retry with exponential backoff. Configure your queue with the same pattern for downstream failures — up to 3 retries with delays, then move to a dead-letter queue for manual inspection.