Webhook handlers are idempotent

Webhook providers (Stripe, Clerk, GitHub, Svix) retry delivery on any 5xx response — which is the correct behavior for eventual consistency. But a webhook handler without idempotency converts that reliability guarantee into a defect multiplier: a transient 500 during payment.succeeded processing means the payment is recorded twice, the fulfillment email sends twice, and the inventory decrements twice. For Stripe specifically, this can cause double charges in your records, triggering refund reconciliation issues that require manual intervention. Idempotency is not an optional hardening step — it is the contract that makes retries safe.

Use a processedWebhook table with a unique constraint on eventId. An atomic insert that rejects duplicates is the cleanest deduplication primitive — no Redis, no TTL expiry, and the processed set is queryable for debugging.

export async function POST(req: Request) {
  const body = await req.text()
  const sig = req.headers.get('stripe-signature')!
  const event = stripe.webhooks.constructEvent(body, sig, process.env.STRIPE_WEBHOOK_SECRET!)

  try {
    await prisma.processedWebhook.create({ data: { eventId: event.id } })
  } catch {
    // Unique constraint violation = already processed
    return Response.json({ ok: true, duplicate: true })
  }

  // Side effects only run once
  if (event.type === 'payment_intent.succeeded') {
    await prisma.payment.create({ data: { ... } })
  }
  return Response.json({ ok: true })
}

The processedWebhooks table needs only eventId TEXT PRIMARY KEY and createdAt TIMESTAMP. Add a cron to purge rows older than 30 days.