stripe-webhooks

Stripe Webhook Security

RULE 1: ALWAYS Verify Webhook Signatures First

The AI will generate webhook handlers that process the payload directly. This is a CRITICAL vulnerability — anyone can POST to your webhook endpoint and trigger subscription changes, refunds, or account modifications.

import Stripe from 'stripe'

const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!)

export async function POST(request: Request) {
  const body = await request.text() // Must be raw text, NOT .json()
  const signature = request.headers.get('stripe-signature')

  if (!signature) {
    return Response.json({ error: 'Missing signature' }, { status: 400 })
  }

  let event: Stripe.Event

  try {
    event = stripe.webhooks.constructEvent(
      body,
      signature,
      process.env.STRIPE_WEBHOOK_SECRET!
    )
  } catch (err) {
    console.error('[STRIPE_WEBHOOK_VERIFICATION_FAILED]', err)
    return Response.json({ error: 'Invalid signature' }, { status: 400 })
  }

  // NOW it's safe to process the event
  switch (event.type) {
    case 'checkout.session.completed':
      await handleCheckoutCompleted(event.data.object)
      break
    case 'customer.subscription.updated':
      await handleSubscriptionUpdated(event.data.object)
      break
    case 'customer.subscription.deleted':
      await handleSubscriptionDeleted(event.data.object)
      break
  }

  return Response.json({ received: true })
}

RULE 2: NEVER Use request.json() for Webhooks

Stripe signature verification requires the RAW request body as a string. If you parse it with request.json() first, the verification will ALWAYS fail because JSON.stringify produces different whitespace than the original payload.

// ❌ WRONG — signature verification will always fail
const body = await request.json()
stripe.webhooks.constructEvent(JSON.stringify(body), sig, secret)

// ✅ CORRECT — use raw text
const body = await request.text()
stripe.webhooks.constructEvent(body, sig, secret)