Payment Webhook Patterns | Bootspring Docs

Handle payment events reliably with Stripe webhooks.

Overview#

Webhooks are essential for reliable payment processing. This pattern covers:

Webhook signature verification
Event handling
Idempotency
Error handling and retries
Testing webhooks locally

Basic Webhook Handler#

Verify and process Stripe webhook events.

// app/api/webhooks/stripe/route.ts
import { stripe } from '@/lib/stripe'
import { headers } from 'next/headers'
import Stripe from 'stripe'

const webhookSecret = process.env.STRIPE_WEBHOOK_SECRET!

export async function POST(request: Request) {
  const body = await request.text()
  const signature = headers().get('stripe-signature')!

  let event: Stripe.Event

  try {
    event = stripe.webhooks.constructEvent(body, signature, webhookSecret)
  } catch (err) {
    console.error('Webhook signature verification failed:', err)
    return Response.json({ error: 'Invalid signature' }, { status: 400 })
  }

  try {
    await handleEvent(event)
    return Response.json({ received: true })
  } catch (err) {
    console.error('Webhook handler error:', err)
    return Response.json({ error: 'Handler failed' }, { status: 500 })
  }
}

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.created':
    case 'customer.subscription.updated':
      await handleSubscriptionUpdate(event.data.object as Stripe.Subscription)
      break

    case 'customer.subscription.deleted':
      await handleSubscriptionDeleted(event.data.object as Stripe.Subscription)
      break

    case 'invoice.paid':
      await handleInvoicePaid(event.data.object as Stripe.Invoice)
      break

    case 'invoice.payment_failed':
      await handlePaymentFailed(event.data.object as Stripe.Invoice)
      break

    default:
      console.log(`Unhandled event type: ${event.type}`)
  }
}

Idempotent Processing#

Prevent duplicate processing of the same event.

// lib/webhooks.ts
import { prisma } from '@/lib/db'

export async function processWebhookOnce(
  eventId: string,
  handler: () => Promise<void>
) {
  // Check if already processed
  const existing = await prisma.webhookEvent.findUnique({
    where: { eventId }
  })

  if (existing?.processedAt) {
    console.log(`Event ${eventId} already processed, skipping`)
    return { skipped: true }
  }

  // Create or update event record
  await prisma.webhookEvent.upsert({
    where: { eventId },
    create: { eventId, receivedAt: new Date() },
    update: {}
  })

  try {
    await handler()

    // Mark as processed
    await prisma.webhookEvent.update({
      where: { eventId },
      data: { processedAt: new Date() }
    })

    return { success: true }
  } catch (error) {
    // Record failure
    await prisma.webhookEvent.update({
      where: { eventId },
      data: {
        error: error instanceof Error ? error.message : 'Unknown error',
        failedAt: new Date()
      }
    })

    throw error
  }
}

// Usage in webhook handler
async function handleEvent(event: Stripe.Event) {
  await processWebhookOnce(event.id, async () => {
    switch (event.type) {
      case 'checkout.session.completed':
        await handleCheckoutComplete(event.data.object)
        break
      // ... other handlers
    }
  })
}

Event Handlers#

Handle specific webhook events.

// lib/webhook-handlers.ts
import { prisma } from '@/lib/db'
import { sendEmail } from '@/lib/email'
import Stripe from 'stripe'

export async function handleCheckoutComplete(session: Stripe.Checkout.Session) {
  const userId = session.metadata?.userId
  if (!userId) return

  if (session.mode === 'subscription') {
    // Subscription handled by subscription webhooks
    return
  }

  // One-time payment
  if (session.mode === 'payment') {
    const lineItems = await stripe.checkout.sessions.listLineItems(session.id)

    // Create order record
    await prisma.order.create({
      data: {
        userId,
        stripeSessionId: session.id,
        amount: session.amount_total!,
        currency: session.currency!,
        status: 'completed',
        items: {
          create: lineItems.data.map(item => ({
            name: item.description!,
            quantity: item.quantity!,
            price: item.price!.unit_amount!
          }))
        }
      }
    })

    // Send confirmation email
    const user = await prisma.user.findUnique({ where: { id: userId } })
    if (user?.email) {
      await sendEmail({
        to: user.email,
        subject: 'Order Confirmation',
        template: 'order-confirmation',
        data: { sessionId: session.id }
      })
    }
  }
}

export async function handleSubscriptionUpdate(subscription: Stripe.Subscription) {
  const customerId = subscription.customer as string

  const user = await prisma.user.findFirst({
    where: { stripeCustomerId: customerId }
  })

  if (!user) {
    console.error('User not found for customer:', customerId)
    return
  }

  await prisma.subscription.upsert({
    where: { userId: user.id },
    create: {
      userId: user.id,
      stripeSubscriptionId: subscription.id,
      stripePriceId: subscription.items.data[0].price.id,
      status: subscription.status,
      currentPeriodStart: new Date(subscription.current_period_start * 1000),
      currentPeriodEnd: new Date(subscription.current_period_end * 1000),
      cancelAtPeriodEnd: subscription.cancel_at_period_end
    },
    update: {
      stripePriceId: subscription.items.data[0].price.id,
      status: subscription.status,
      currentPeriodStart: new Date(subscription.current_period_start * 1000),
      currentPeriodEnd: new Date(subscription.current_period_end * 1000),
      cancelAtPeriodEnd: subscription.cancel_at_period_end
    }
  })
}

export async function handlePaymentFailed(invoice: Stripe.Invoice) {
  const customerId = invoice.customer as string

  const user = await prisma.user.findFirst({
    where: { stripeCustomerId: customerId }
  })

  if (!user) return

  // Record failed payment
  await prisma.paymentAttempt.create({
    data: {
      userId: user.id,
      stripeInvoiceId: invoice.id,
      amount: invoice.amount_due,
      status: 'failed',
      failedAt: new Date()
    }
  })

  // Send notification email
  await sendEmail({
    to: user.email,
    subject: 'Payment Failed',
    template: 'payment-failed',
    data: {
      amount: invoice.amount_due,
      currency: invoice.currency,
      updateUrl: `${process.env.NEXT_PUBLIC_URL}/settings/billing`
    }
  })
}

Webhook Event Schema#

Prisma schema for tracking webhook events.

// prisma/schema.prisma
model WebhookEvent {
  id          String    @id @default(cuid())
  eventId     String    @unique
  receivedAt  DateTime
  processedAt DateTime?
  error       String?
  failedAt    DateTime?
  createdAt   DateTime  @default(now())
}

model PaymentAttempt {
  id              String   @id @default(cuid())
  userId          String
  stripeInvoiceId String
  amount          Int
  status          String
  failedAt        DateTime?
  createdAt       DateTime @default(now())

  user User @relation(fields: [userId], references: [id])
}

Testing Webhooks Locally#

Use Stripe CLI to test webhooks during development.

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

# Login to Stripe
stripe login

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

# In another terminal, trigger test events
stripe trigger checkout.session.completed
stripe trigger customer.subscription.updated
stripe trigger invoice.payment_failed

# Trigger with specific data
stripe trigger checkout.session.completed \
  --override checkout_session:metadata.userId=user_123

Webhook Configuration#

Configure webhooks in Stripe Dashboard or via API.

// scripts/setup-webhooks.ts
import { stripe } from '@/lib/stripe'

async function setupWebhooks() {
  const webhookEndpoint = await stripe.webhookEndpoints.create({
    url: 'https://your-domain.com/api/webhooks/stripe',
    enabled_events: [
      'checkout.session.completed',
      'customer.subscription.created',
      'customer.subscription.updated',
      'customer.subscription.deleted',
      'invoice.paid',
      'invoice.payment_failed',
      'customer.updated'
    ]
  })

  console.log('Webhook endpoint created:', webhookEndpoint.id)
  console.log('Webhook secret:', webhookEndpoint.secret)
}

setupWebhooks()

Best Practices#

Always verify signatures - Never process unverified webhooks
Handle idempotently - Events may be sent multiple times
Return 200 quickly - Process asynchronously if needed
Log all events - Maintain audit trail for debugging
Monitor failures - Set up alerts for failed webhook processing

Stripe - Stripe setup
Subscriptions - Subscription events
Checkout - Checkout completion events