The Complete Production SOP: How to Deploy and Run Stripe Checkout & Idempotent Webhook Processing in Autonomous AI Agents

---
name: "stripe-checkout-webhook-idempotency"
description: "Handle payments, subscriptions, and webhook events safely with signature verification."
metadata:
  author: "Stripe"
  version: "1.0.0"
  runtime_compatibility:
    - "codex"
    - "claude-code"
    - "cursor"
    - "windsurf"
triggers:
  - "create stripe checkout session"
  - "verify stripe webhook signature"
  - "handle stripe idempotency"
permissions:
  fs_read: true
  fs_write: "workspace"
  shell_exec: false
  net_access: false
---

import { headers } from 'next/headers';
import { NextResponse } from 'next/server';
import Stripe from 'stripe';
import { db } from '@/lib/db';

const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!, {
  apiVersion: '2023-10-16',
});

export async function POST(req: Request) {
  const rawBody = await req.text();
  const signature = headers().get('stripe-signature');

  if (!signature) {
    return new NextResponse('Missing stripe-signature header', { status: 400 });
  }

  let event: Stripe.Event;
  try {
    event = stripe.webhooks.constructEvent(
      rawBody,
      signature,
      process.env.STRIPE_WEBHOOK_SECRET!
    );
  } catch (err: any) {
    return new NextResponse(`Webhook Error: ${err.message}`, { status: 400 });
  }

  // Idempotent processing gate
  const isProcessed = await db.processedWebhookEvent.findUnique({
    where: { eventId: event.id },
  });

  if (isProcessed) {
    return NextResponse.json({ received: true, deduplicated: true });
  }

  await db.$transaction(async (tx) => {
    await tx.processedWebhookEvent.create({
      data: { eventId: event.id, eventType: event.type },
    });
    if (event.type === 'checkout.session.completed') {
      const session = event.data.object as Stripe.Checkout.Session;
      await tx.user.update({
        where: { id: session.client_reference_id! },
        data: { subscriptionStatus: 'ACTIVE' },
      });
    }
  });

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