Stripe Webhooks in Production: The Idempotency Guide Nobody Writes

// app/api/webhooks/stripe/route.ts
import { NextRequest, NextResponse } from 'next/server';
import Stripe from 'stripe';
import { db } from '@/db';
import { webhookEvents, subscriptions } from '@/db/schema';
import { eq } from 'drizzle-orm';

const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!, {
  apiVersion: '2024-12-18.acacia',
});

export async function POST(req: NextRequest) {
  const body = await req.text();
  const sig = req.headers.get('stripe-signature')!;

  let event: Stripe.Event;

  // Step 1: Verify the signature
  try {
    event = stripe.webhooks.constructEvent(
      body,
      sig,
      process.env.STRIPE_WEBHOOK_SECRET!
    );
  } catch (err) {
    console.error('Webhook signature verification failed:', err);
    return NextResponse.json({ error: 'Invalid signature' }, { status: 400 });
  }

  // Step 2: Idempotency check — have we processed this event before?
  const existing = await db.query.webhookEvents.findFirst({
    where: eq(webhookEvents.stripeEventId, event.id),
  });

  if (existing) {
    // Already processed — return 200 so Stripe stops retrying
    console.log(`Duplicate event ${event.id} — skipping`);
    return NextResponse.json({ received: true, duplicate: true });
  }

  // Step 3: Record the event as being processed (BEFORE processing)
  await db.insert(webhookEvents).values({
    stripeEventId: event.id,
    type: event.type,
    status: 'processing',
    receivedAt: new Date(),
  });

  // Step 4: Handle the event
  try {
    await handleEvent(event);

    // Mark as complete
    await db.update(webhookEvents)
      .set({ status: 'completed', processedAt: new Date() })
      .where(eq(webhookEvents.stripeEventId, event.id));
  } catch (error) {
    // Mark as failed — but still return 200 for non-retriable errors
    await db.update(webhookEvents)
      .set({ 
        status: 'failed', 
        error: error instanceof Error ? error.message : String(error),
        processedAt: new Date(),
      })
      .where(eq(webhookEvents.stripeEventId, event.id));

    // Return 500 only for retriable errors (transient failures)
    // Return 200 for permanent failures (bad data, etc.) to stop retries
    const isRetriable = error instanceof Error && 
      error.message.includes('ECONNRESET');

    if (isRetriable) {
      // Delete the event record so Stripe can retry and we'll try again
      await db.delete(webhookEvents)
        .where(eq(webhookEvents.stripeEventId, event.id));
      return NextResponse.json({ error: 'Processing failed' }, { status: 500 });
    }
  }

  return NextResponse.json({ received: true });
}

// db/schema.ts
import { pgTable, text, timestamp, uuid } from 'drizzle-orm/pg-core';

export const webhookEvents = pgTable('webhook_events', {
  id: uuid('id').primaryKey().defaultRandom(),
  stripeEventId: text('stripe_event_id').notNull().unique(),  // unique prevents duplicates
  type: text('type').notNull(),
  status: text('status').notNull(),  // processing | completed | failed
  error: text('error'),
  receivedAt: timestamp('received_at').notNull(),
  processedAt: timestamp('processed_at'),
});

async function handleEvent(event: Stripe.Event) {
  switch (event.type) {
    case 'checkout.session.completed':
      await handleCheckoutComplete(event.data.object as Stripe.Checkout.Session);
      break;
    case 'customer.subscription.updated':
      await handleSubscriptionUpdate(event.data.object as Stripe.Subscription);
      break;
    case 'customer.subscription.deleted':
      await handleSubscriptionCancel(event.data.object as Stripe.Subscription);
      break;
    case 'invoice.payment_failed':
      await handlePaymentFailed(event.data.object as Stripe.Invoice);
      break;
    default:
      console.log(`Unhandled event type: ${event.type}`);
  }
}

async function handleCheckoutComplete(session: Stripe.Checkout.Session) {
  const userId = session.metadata?.userId;
  if (!userId) throw new Error(`No userId in session metadata: ${session.id}`);

  // Idempotent upsert — if subscription already exists, update it
  await db.insert(subscriptions)
    .values({
      userId,
      stripeCustomerId: session.customer as string,
      stripeSubscriptionId: session.subscription as string,
      status: 'active',
      plan: session.metadata?.plan ?? 'pro',
      createdAt: new Date(),
    })
    .onConflictDoUpdate({
      target: subscriptions.userId,  // or stripeSubscriptionId
      set: {
        status: 'active',
        stripeSubscriptionId: session.subscription as string,
      },
    });

  // Send welcome email — make this idempotent too
  await sendWelcomeEmail(userId, { once: true });  // internal dedup by userId
}

async function handleSubscriptionUpdate(subscription: Stripe.Subscription) {
  // Fetch the full subscription from Stripe — webhook data can be stale
  // especially on retries
  const fresh = await stripe.subscriptions.retrieve(subscription.id);

  await db.update(subscriptions)
    .set({
      status: fresh.status,
      currentPeriodEnd: new Date(fresh.current_period_end * 1000),
      cancelAtPeriodEnd: fresh.cancel_at_period_end,
    })
    .where(eq(subscriptions.stripeSubscriptionId, subscription.id));
}

Worker A: INSERT webhook_event (id=evt_123, status=processing) ← succeeds
Worker B: INSERT webhook_event (id=evt_123, status=processing) ← unique violation
Worker B: catches error, returns 200 (safe — Worker A has it)
Worker A: processes event, updates status=completed

async function processWithLock(eventId: string, fn: () => Promise<void>) {
  // Postgres advisory lock — only one worker processes at a time
  const lockKey = hashCode(eventId);  // convert to int32

  await db.execute(sql`SELECT pg_advisory_lock(${lockKey})`);
  try {
    await fn();
  } finally {
    await db.execute(sql`SELECT pg_advisory_unlock(${lockKey})`);
  }
}

# Install Stripe CLI
brew install stripe/stripe-cli/stripe

# Forward events to your local server
stripe listen --forward-to localhost:3000/api/webhooks/stripe

# Trigger a test event
stripe trigger checkout.session.completed

# Test idempotency: send the same event twice
stripe events resend evt_1234567890  # resend a specific event

// Show all payment events for a customer
const events = await db.query.webhookEvents.findMany({
  where: and(
    like(webhookEvents.type, 'invoice.%'),
    eq(webhookEvents.status, 'completed')
  ),
  orderBy: desc(webhookEvents.receivedAt),
  limit: 50,
});