The Complete Production SOP: How to Deploy and Run Stripe Elements & Webhook Idempotency in Autonomous AI Agents

---
name: "stripe-billing"
description: "Implement Stripe Checkout sessions, subscription upgrades, customer portals, and idempotent webhooks."
triggers:
  - "setup stripe webhook"
  - "create checkout session"
  - "handle subscription upgrade"
  - "add idempotency key"
---

# Stripe Elements & Webhook Idempotency SOP

1. ALWAYS construct Stripe webhook handlers using the raw request buffer to verify `stripe-signature`.
2. Store incoming `event.id` in a dedicated `processed_webhook_events` table before executing side-effects.
3. Return HTTP 200 immediately if `event.id` already exists (deterministic idempotency).
4. When creating Checkout Sessions, always supply `idempotencyKey` and `customer` ID to prevent customer duplication.

import Stripe from 'stripe';

if (!process.env.STRIPE_SECRET_KEY) {
  throw new Error('STRIPE_SECRET_KEY is missing from environment variables');
}

export const stripe = new Stripe(process.env.STRIPE_SECRET_KEY, {
  apiVersion: '2024-12-18.acacia',
  typescript: true,
  appInfo: {
    name: 'AutonomousBillingIntegration',
    version: '1.0.0',
  },
});

import { NextRequest, NextResponse } from 'next/server';
import { stripe } from '@/lib/stripe';
import { db } from '@/lib/db';

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

  if (!signature || !process.env.STRIPE_WEBHOOK_SECRET) {
    return NextResponse.json({ error: 'Missing webhook configuration' }, { status: 400 });
  }

  let event;
  try {
    event = stripe.webhooks.constructEvent(
      body,
      signature,
      process.env.STRIPE_WEBHOOK_SECRET
    );
  } catch (err: any) {
    return NextResponse.json({ error: `Webhook Error: ${err.message}` }, { status: 400 });
  }

  // Idempotency Gate: Prevent duplicate processing
  const isDuplicate = await db.processedEvent.findUnique({ where: { eventId: event.id } });
  if (isDuplicate) {
    return NextResponse.json({ received: true, deduplicated: true }, { status: 200 });
  }

  await db.$transaction([
    db.processedEvent.create({ data: { eventId: event.id, type: event.type } }),
    // Business logic mutations mapped to event.type...
  ]);

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

import { describe, it, expect, vi } from 'vitest';
import { POST } from '@/app/api/webhooks/stripe/route';

describe('Stripe Webhook Idempotency Verification', () => {
  it('should acknowledge but ignore previously processed event IDs', async () => {
    const mockReq = {
      text: async () => JSON.stringify({ id: 'evt_test_123', type: 'customer.subscription.updated' }),
      headers: new Headers({ 'stripe-signature': 'valid_sig' })
    } as any;
    
    // First invocation processes, second invocation must deduplicate
    const res = await POST(mockReq);
    expect(res.status).toBe(200);
  });
});