Webhooks & Customer Portal

Lemon Squeezy (event occurs)
    |
    v
POST /api/webhooks/lemonsqueezy
    |
    |--- 1. Rate limiting (Upstash Redis)
    |--- 2. Read raw body (needed for signature)
    |--- 3. Get X-Signature header
    |--- 4. HMAC-SHA256 verification
    |         |--- FAIL → 401 Unauthorized
    |         |--- PASS → continue
    |
    v
Parse Payload
    |--- Extract event_name from meta
    |--- Extract userId from custom_data
    |--- Validate userId present
    |
    v
Route to Handler (switch on event_name)
    |--- subscription_created  → handleSubscriptionCreated()
    |--- subscription_updated  → handleSubscriptionUpdated()
    |--- subscription_cancelled → handleSubscriptionCancelled()
    |--- ... (11 total events)
    |
    v
Return 200 OK (always, even on handler errors)

/**
 * Lemon Squeezy Webhook Handler
 * Processes subscription and payment events with modular handlers
 */

import { NextRequest, NextResponse } from 'next/server'
import type { WebhookPayload } from '@/lib/payments/types'
import { verifyWebhookSignature } from './lib/signature-verification'
import {
  extractUserId,
  logWebhookEvent,
  logWebhookError,
} from './lib/webhook-helpers'
import {
  handleSubscriptionCreated,
  handleSubscriptionUpdated,
  handleSubscriptionCancelled,
  handleSubscriptionResumed,
  handleSubscriptionExpired,
  handleSubscriptionPaused,
  handleSubscriptionUnpaused,
  handlePaymentFailed,
  handlePaymentSuccess,
  handlePaymentRecovered,
  handleOrderCreated,
} from './handlers'
import { withRateLimit } from '@/lib/security/rate-limit-middleware'

// Disable body parsing, we need the raw body for signature verification
export const runtime = 'nodejs'

export const POST = withRateLimit('webhooks', async (request: NextRequest) => {
  try {
    // Verify webhook signature
    const verificationResult = await verifyWebhookSignature(request)

    if (!verificationResult.isValid) {
      logWebhookError(
        verificationResult.error || 'Signature verification failed'
      )
      return NextResponse.json(
        { error: verificationResult.error },
        {
          status: verificationResult.error?.includes('not configured')
            ? 500
            : 401,
        }
      )
    }

    // Parse the webhook payload
    const payload: WebhookPayload = JSON.parse(verificationResult.rawBody!)

    // Extract event data
    const eventName = payload.meta.event_name
    const userId = extractUserId(payload)

    // Log incoming webhook event with more details
    logWebhookEvent(`Webhook received: ${eventName}`, {
      eventName,
      subscriptionId: payload.data?.id,
      userId,
      customData: payload.meta.custom_data,
      testMode: payload.meta.test_mode,
      timestamp: new Date().toISOString(),
    })

    if (!userId) {
      logWebhookError('No userId in custom data', {
        eventName,
        customData: payload.meta.custom_data,
      })
      return NextResponse.json(
        { error: 'No userId in custom data' },
        { status: 400 }
      )
    }

    // Handle different event types with proper error handling
    try {
      switch (eventName) {
        case 'subscription_created':
          await handleSubscriptionCreated(payload, String(userId))
          break

        case 'subscription_updated':
          await handleSubscriptionUpdated(payload, String(userId))
          break

        case 'subscription_cancelled':
          await handleSubscriptionCancelled(payload, String(userId))
          break

        case 'subscription_resumed':
          await handleSubscriptionResumed(payload, String(userId))
          break

        case 'subscription_expired':
          await handleSubscriptionExpired(payload, String(userId))
          break

        case 'subscription_paused':
          await handleSubscriptionPaused(payload, String(userId))
          break

        case 'subscription_unpaused':
          await handleSubscriptionUnpaused(payload, String(userId))
          break

        case 'subscription_payment_failed':
          await handlePaymentFailed(payload, String(userId))
          break

        case 'subscription_payment_success':
          await handlePaymentSuccess(payload, String(userId))
          break

        case 'subscription_payment_recovered':
          await handlePaymentRecovered(payload, String(userId))
          break

        case 'order_created':
          await handleOrderCreated(payload, String(userId))
          break

        default:
          logWebhookEvent(`Unhandled webhook event: ${eventName}`)
      }

      logWebhookEvent(`Webhook processed successfully: ${eventName}`)
      return NextResponse.json({ received: true }, { status: 200 })
    } catch (handlerError) {
      logWebhookError(`Error in handler for ${eventName}:`, handlerError)
      // Return 200 to prevent Lemon Squeezy from retrying
      // but log the error for debugging
      return NextResponse.json(
        { received: true, error: 'Handler error logged' },
        { status: 200 }
      )
    }
  } catch (error) {
    logWebhookError('Webhook processing error:', error)
    return NextResponse.json(
      { error: 'Webhook processing failed' },
      { status: 500 }
    )
  }
})

export async function verifyWebhookSignature(
  request: NextRequest
): Promise<VerificationResult> {
  try {
    // Get the raw body
    const rawBody = await request.text()

    // Get the signature from headers (case-insensitive)
    const signatureHeader =
      request.headers.get('x-signature') || request.headers.get('X-Signature')

    if (!signatureHeader) {
      return {
        isValid: false,
        error: 'No signature provided',
      }
    }

    // Verify webhook secret is configured
    const secret = process.env.LEMONSQUEEZY_WEBHOOK_SECRET
    if (!secret) {
      return {
        isValid: false,
        error: 'Webhook secret not configured',
      }
    }

    // Convert signature from hex string to Buffer
    const signature = Buffer.from(signatureHeader, 'hex')

    // Create HMAC hash and convert to Buffer
    const hmac = Buffer.from(
      crypto.createHmac('sha256', secret).update(rawBody).digest('hex'),
      'hex'
    )

    // Verify both buffers have same length before comparing
    if (signature.length === 0 || hmac.length === 0) {
      return {
        isValid: false,
        error: 'Invalid signature format',
      }
    }

    // Compare signatures using timing-safe comparison
    const signatureValid =
      signature.length === hmac.length &&
      crypto.timingSafeEqual(hmac, signature)

    if (!signatureValid) {
      return {
        isValid: false,
        error: 'Signature verification failed',
      }
    }

    return {
      isValid: true,
      rawBody,
    }
  } catch (error) {
    return {
      isValid: false,
      error: `Verification error: ${error instanceof Error ? error.message : 'Unknown error'}`,
    }
  }
}

apps/boilerplate/src/app/api/webhooks/lemonsqueezy/
├── route.ts                    # Entry point, signature verification, routing
├── handlers/
│   ├── index.ts                # Barrel export for all handlers
│   ├── subscription-created.ts
│   ├── subscription-updated.ts
│   ├── subscription-cancelled.ts
│   ├── subscription-resumed.ts
│   ├── subscription-expired.ts
│   ├── subscription-paused.ts
│   ├── subscription-unpaused.ts
│   ├── payment-success.ts
│   ├── payment-failed.ts
│   ├── payment-recovered.ts
│   └── order-created.ts
├── lib/
│   ├── signature-verification.ts
│   └── webhook-helpers.ts      # Logging, userId extraction
└── types.ts                    # SubscriptionAttributes, webhook types

try {
  switch (eventName) {
    case 'subscription_created':
      await handleSubscriptionCreated(payload, userId)
      break
    // ... other events
  }
  return NextResponse.json({ received: true }, { status: 200 })
} catch (handlerError) {
  logWebhookError(`Error in handler for ${eventName}:`, handlerError)
  // Return 200 to prevent retries — error is logged
  return NextResponse.json(
    { received: true, error: 'Handler error logged' },
    { status: 200 }
  )
}

import { getCustomerPortal } from '@/lib/payments/subscription'

// In an API route
export async function GET(request: NextRequest) {
  const userId = getCurrentUserId(request)
  const { portalUrl } = await getCustomerPortal(userId)

  return NextResponse.redirect(portalUrl)
}