Stripe Supabase Webhooks

Always verify signatures before processing:

export async function POST(req: NextRequest) {
  const rawBody = Buffer.from(await req.arrayBuffer());
  const sig = req.headers.get('stripe-signature') ?? '';

  let event: Stripe.Event;
  try {
    event = stripe.webhooks.constructEvent(
      rawBody,
      sig,
      process.env.STRIPE_WEBHOOK_SECRET!,
    );
  } catch (err) {
    console.warn('Signature verification failed:', err);
    return NextResponse.json({ error: 'Invalid signature' }, { status: 400 });
  }

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

3. Cascading Upsert Strategy

When syncing Stripe data to Supabase, use a cascading lookup strategy to handle various user identification scenarios:

async function upsertSubscriber(fields: {
  stripeCustomerId: string;
  stripeSubscriptionId?: string;
  userId?: string;        // From auth
  email?: string;         // From Stripe customer
  plan?: string;
  status?: Stripe.Subscription.Status | 'expired';
  hasCard?: boolean;
  trialEnd?: number | null;
}) {
  const updateData = {
    stripe_customer_id: fields.stripeCustomerId,
    stripe_subscription_id: fields.stripeSubscriptionId,
    email: fields.email,
    plan: fields.plan,
    status: fields.status,
    has_card: fields.hasCard,
    trial_end: fields.trialEnd,
    updated_at: new Date().toISOString(),
  };

  // Priority 1: Update by user_id (most reliable for authenticated users)
  if (fields.userId) {
    const { data: existing } = await supa
      .from('subscribers')
      .select('id')
      .eq('user_id', fields.userId)
      .maybeSingle();

    if (existing) {
      await supa.from('subscribers').update(updateData).eq('user_id', fields.userId);
      return;
    }
  }

  // Priority 2: Update by email (handles pre-signup records)
  if (fields.email) {
    const { data: existing } = await supa
      .from('subscribers')
      .select('id')
      .eq('email', fields.email)
      .maybeSingle();

    if (existing) {
      await supa.from('subscribers').update(updateData).eq('email', fields.email);
      return;
    }
  }

  // Priority 3: Upsert by stripe_customer_id (fallback)
  await supa
    .from('subscribers')
    .upsert(updateData, { onConflict: 'stripe_customer_id' });
}

4. Event Type Handling

Handle subscription lifecycle events with proper customer data retrieval:

switch (event.type) {
  case 'checkout.session.completed': {
    const session = event.data.object as Stripe.Checkout.Session;
    const custId = session.customer as string;
    const subId = session.subscription as string;

    const customer = await stripe.customers.retrieve(custId) as Stripe.Customer;
    const subscription = await stripe.subscriptions.retrieve(subId);

    await upsertSubscriber({
      stripeCustomerId: custId,
      stripeSubscriptionId: subId,
      userId: session.metadata?.userId || session.client_reference_id,
      email: customer.email ?? session.customer_details?.email ?? '',
      plan: planFromPrice(subscription.items.data[0]?.price.id ?? ''),
      status: subscription.status,
      hasCard: true,
      trialEnd: subscription.trial_end,
    });

    // Send welcome email
    if (customer.email) {
      await EmailService.sendWelcomeEmail(customer.email, plan);
    }
    break;
  }

  case 'customer.subscription.updated': {
    const sub = event.data.object as Stripe.Subscription;
    const customer = await stripe.customers.retrieve(sub.customer as string) as Stripe.Customer;

    await upsertSubscriber({
      stripeCustomerId: sub.customer as string,
      stripeSubscriptionId: sub.id,
      email: customer.email ?? '',
      plan: planFromPrice(sub.items.data[0]?.price.id ?? ''),
      status: sub.status,
      hasCard: cardOnFile(customer),
      trialEnd: sub.trial_end,
    });
    break;
  }

  case 'customer.subscription.deleted': {
    const sub = event.data.object as Stripe.Subscription;
    await upsertSubscriber({
      stripeCustomerId: sub.customer as string,
      stripeSubscriptionId: sub.id,
      status: 'canceled',
      hasCard: false,
    });
    break;
  }

  case 'invoice.payment_succeeded':
  case 'invoice.payment_failed': {
    const inv = event.data.object as Stripe.Invoice;
    const customer = await stripe.customers.retrieve(inv.customer as string) as Stripe.Customer;

    await upsertSubscriber({
      stripeCustomerId: inv.customer as string,
      stripeSubscriptionId: inv.subscription as string | undefined,
      email: customer.email ?? '',
      status: inv.status as Stripe.Subscription.Status,
    });
    break;
  }
}

5. Helper Functions

/** Check if customer has payment method on file */
function cardOnFile(cust: Stripe.Customer): boolean {
  return Boolean(
    cust.invoice_settings?.default_payment_method || cust.default_source
  );
}

/** Map Stripe price ID to internal plan name */
function planFromPrice(priceId: string): string {
  const PRICE_MAP: Record<string, string> = {
    [process.env.STRIPE_MONTHLY_PRICE_ID!]: 'monthly',
    [process.env.STRIPE_ANNUAL_PRICE_ID!]: 'annual',
  };
  return PRICE_MAP[priceId] ?? 'unknown';
}

Key Events to Handle

Database Schema Requirements

CREATE TABLE subscribers (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  user_id UUID UNIQUE REFERENCES auth.users(id),
  email TEXT,
  stripe_customer_id TEXT UNIQUE,
  stripe_subscription_id TEXT,
  plan TEXT CHECK (plan IN ('monthly', 'annual', 'unknown')),
  status TEXT,
  has_card BOOLEAN DEFAULT false,
  trial_end BIGINT,
  created_at TIMESTAMPTZ DEFAULT now(),
  updated_at TIMESTAMPTZ DEFAULT now()
);

CREATE INDEX idx_subscribers_email ON subscribers(email);
CREATE INDEX idx_subscribers_stripe_customer ON subscribers(stripe_customer_id);

Environment Variables

STRIPE_SECRET_KEY=sk_live_...
STRIPE_WEBHOOK_SECRET=whsec_...
STRIPE_MONTHLY_PRICE_ID=price_...
STRIPE_ANNUAL_PRICE_ID=price_...
NEXT_PUBLIC_SUPABASE_URL=https://xxx.supabase.co
SUPABASE_SERVICE_ROLE_KEY=eyJ...

Testing Webhooks Locally

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

# Forward webhooks to local dev server
stripe listen --forward-to localhost:3000/api/stripe-webhook

# Trigger test events
stripe trigger checkout.session.completed
stripe trigger customer.subscription.updated
stripe trigger invoice.payment_failed

References

See references/event-handling.md for detailed event payload examples and edge cases.