Webhook Security in Next.js: Signatures, Idempotency, and Avoiding Common Mistakes

#nextjs #security #stripe #webdev

Webhooks are one of the most common attack surfaces in developer applications. They receive unauthenticated POST requests from the internet, execute code based on that input, and often trigger irreversible actions like sending emails or processing payments.

Here's how to secure them properly.

The Core Risk

An unsecured webhook endpoint accepts requests from anyone. An attacker who discovers your Stripe webhook URL can send fake payment events and trigger product delivery without paying. An attacker who finds your GitHub webhook can trigger deployments at will.

Webhook security has three layers: authentication, validation, and idempotency.

Layer 1: Verify the Signature

Every serious webhook provider (Stripe, GitHub, Twilio, Shopify) signs their requests with a secret. Always verify that signature before doing anything with the payload.

Stripe Webhooks

// src/app/api/webhooks/stripe/route.ts
import { NextRequest, NextResponse } from "next/server"
import Stripe from "stripe"

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

export async function POST(req: NextRequest) {
  const body = await req.text()  // Must read as text, not JSON
  const sig = req.headers.get("stripe-signature")

  if (!sig) {
    return NextResponse.json({ error: "No signature" }, { status: 400 })
  }

  let event: Stripe.Event
  try {
    event = stripe.webhooks.constructEvent(body, sig, webhookSecret)
  } catch (err) {
    // Invalid signature -- reject immediately
    return NextResponse.json({ error: "Invalid signature" }, { status: 400 })
  }

  // Now safe to process
  await handleEvent(event)
  return NextResponse.json({ received: true })
}

GitHub Webhooks

import { createHmac, timingSafeEqual } from "crypto"

function verifyGitHubSignature(
  payload: string,
  signature: string | null,
  secret: string
): boolean {
  if (!signature) return false

  const expectedSig = "sha256=" + createHmac("sha256", secret)
    .update(payload)
    .digest("hex")

  // Use timingSafeEqual to prevent timing attacks
  const a = Buffer.from(signature)
  const b = Buffer.from(expectedSig)

  if (a.length !== b.length) return false
  return timingSafeEqual(a, b)
}

export async function POST(req: NextRequest) {
  const body = await req.text()
  const sig = req.headers.get("x-hub-signature-256")

  if (!verifyGitHubSignature(body, sig, process.env.GITHUB_WEBHOOK_SECRET!)) {
    return NextResponse.json({ error: "Invalid signature" }, { status: 401 })
  }

  const event = JSON.parse(body)
  // process...
}

Critical detail: Always read the body as raw text before signature verification. Parsing it as JSON first can alter whitespace and break the signature check.

Layer 2: Validate the Payload

Even after signature verification, validate the structure and types of the payload. Don't assume the webhook provider's schema is stable.

import { z } from "zod"

const StripePaymentSchema = z.object({
  type: z.string(),
  data: z.object({
    object: z.object({
      id: z.string(),
      amount: z.number().positive(),
      currency: z.string().length(3),
      status: z.enum(["succeeded", "pending", "failed"]),
      customer: z.string().nullable(),
    })
  })
})

async function handleEvent(event: Stripe.Event) {
  const parsed = StripePaymentSchema.safeParse(event)
  if (!parsed.success) {
    console.error("Unexpected payload shape:", parsed.error)
    return  // Don't process malformed events
  }

  const { type, data } = parsed.data
  // Now TypeScript knows exactly what shape data is
}

Layer 3: Idempotency

Webhook providers retry on failure. If your server returns a 500, Stripe will resend the event -- sometimes dozens of times. Without idempotency, you'll deliver the same product twice, charge the customer twice, or send duplicate emails.

import { db } from "@/lib/db"

async function handlePaymentSucceeded(event: Stripe.Event) {
  // Check if already processed
  const existing = await db.webhookEvent.findUnique({
    where: { stripeEventId: event.id }
  })

  if (existing) {
    console.log("Duplicate event, skipping:", event.id)
    return  // Already handled
  }

  // Process the event
  await deliverProduct(event.data.object)
  await sendConfirmationEmail(event.data.object)

  // Mark as processed (do this AFTER successful processing)
  await db.webhookEvent.create({
    data: {
      stripeEventId: event.id,
      type: event.type,
      processedAt: new Date(),
    }
  })
}

Add the model to your Prisma schema:

model WebhookEvent {
  id            String   @id @default(cuid())
  stripeEventId String   @unique
  type          String
  processedAt   DateTime @default(now())
}

Layer 4: Process Asynchronously

Webhook providers expect a fast response (usually under 5 seconds). If your handler does heavy work -- sending emails, calling external APIs, running database migrations -- you'll timeout.

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

  let event: Stripe.Event
  try {
    event = stripe.webhooks.constructEvent(body, sig!, webhookSecret)
  } catch {
    return NextResponse.json({ error: "Invalid" }, { status: 400 })
  }

  // Acknowledge immediately
  // Queue for async processing
  await db.webhookQueue.create({
    data: {
      eventId: event.id,
      type: event.type,
      payload: JSON.stringify(event),
      status: "pending",
    }
  })

  return NextResponse.json({ received: true })  // Fast response to Stripe
}

// Separate worker processes the queue
async function processWebhookQueue() {
  const pending = await db.webhookQueue.findMany({
    where: { status: "pending" },
    take: 10,
  })

  for (const item of pending) {
    await processEvent(JSON.parse(item.payload))
    await db.webhookQueue.update({
      where: { id: item.id },
      data: { status: "completed" }
    })
  }
}

Layer 5: Rate Limiting and IP Allowlisting

For extra hardening:

// IP allowlist for Stripe webhooks
const STRIPE_IPS = [
  "3.18.12.63", "3.130.192.231", "13.235.14.237",
  // Full list at: https://stripe.com/docs/ips
]

export async function POST(req: NextRequest) {
  const ip = req.headers.get("x-forwarded-for")?.split(",")[0].trim()

  if (ip && !STRIPE_IPS.includes(ip)) {
    return NextResponse.json({ error: "Forbidden" }, { status: 403 })
  }

  // continue with signature verification...
}

Note: IP allowlisting is defense-in-depth, not a replacement for signature verification. IP addresses can be spoofed; cryptographic signatures cannot.

Common Mistakes

Reading body as JSON before verification: Breaks the signature check. Always read as raw text first.

Skipping idempotency: Causes duplicate actions on retries. Always check if you've seen the event ID before.

Synchronous heavy processing: Causes timeouts and retries. Queue and process asynchronously.

Logging full payloads: Webhook payloads can contain PII and payment data. Log event IDs and types, not full payloads.

Not handling all event types: Return 200 for event types you don't handle. Returning 4xx causes retries.

switch (event.type) {
  case "payment_intent.succeeded":
    await handlePaymentSucceeded(event)
    break
  case "customer.subscription.deleted":
    await handleSubscriptionCanceled(event)
    break
  default:
    // Acknowledge but don't process unknown events
    console.log("Unhandled event type:", event.type)
}

return NextResponse.json({ received: true })  // Always 200