webhook

Razorpay Webhook Handler

Build a webhook handler that survives production chaos: duplicate events, race conditions, out-of-order delivery, and partial failures.

Critical Rules

1. Always return 200 for events you don't handle — Razorpay retries on non-2xx
2. Verify signature FIRST before any processing
3. Idempotency is mandatory — Razorpay uses at-least-once delivery
4. Never trust event order — subscription.charged may arrive before subscription.activated

Signature Verification

import crypto from "crypto";

function verifyWebhookSignature(rawBody: string, signature: string, secret: string): boolean {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(rawBody)
    .digest("hex");

  // MUST use timing-safe comparison to prevent timing attacks
  try {
    return crypto.timingSafeEqual(
      Buffer.from(expected, "hex"),
      Buffer.from(signature, "hex")
    );
  } catch {
    return false; // Length mismatch = invalid
  }
}

Full Webhook Route

// app/api/billing/webhook/route.ts
import crypto from "crypto";

export async function POST(request: Request) {
  // 1. Read raw body (NOT parsed JSON — signature is computed on raw string)
  const rawBody = await request.text();
  const signature = request.headers.get("x-razorpay-signature");

  if (!signature) {
    return new Response("Missing signature", { status: 400 });
  }

  // 2. Verify signature
  const isValid = verifyWebhookSignature(
    rawBody,
    signature,
    process.env.RAZORPAY_WEBHOOK_SECRET!
  );

  if (!isValid) {
    return new Response("Invalid signature", { status: 400 });
  }

  // 3. Parse event
  const event = JSON.parse(rawBody);
  const eventType = event.event;

  // 4. Extract event ID (prefer header over payload)
  const eventId = request.headers.get("x-razorpay-event-id") || event.id || null;

  // 5. Extract subscription ID (multi-path — different event types store it differently)
  const subscriptionId = extractSubscriptionId(event);
  if (!subscriptionId) {
    // Non-subscription event (standalone payment, order, etc.) — acknowledge and skip
    return new Response("OK", { status: 200 });
  }

  // 6. Idempotency check (multi-layer)
  const subscription = await getSubscriptionByRazorpayId(subscriptionId);

  // Layer 1: Exact event ID match (same event delivered twice)
  if (subscription?.lastEventId === eventId && eventId) {
    return new Response("Already processed", { status: 200 });
  }

  // Layer 2: Check processed_events table for this event ID
  // Razorpay can send the same logical event with different event IDs on retry
  if (eventId) {
    const alreadyProcessed = await db
      .select()
      .from(processedWebhookEvents)
      .where(eq(processedWebhookEvents.eventId, eventId))
      .limit(1);
    if (alreadyProcessed.length > 0) {
      return new Response("Already processed", { status: 200 });
    }
  }

  // 7. Handle event
  try {
    await handleEvent(eventType, event, subscription, eventId);

    // Record processed event for idempotency
    if (eventId) {
      await db.insert(processedWebhookEvents).values({
        eventId,
        eventType,
        subscriptionId,
        processedAt: new Date(),
      }).onConflictDoNothing();  // Safe if duplicate insert races
    }
  } catch (error) {
    console.error("Webhook processing error:", error);
    // Still return 200 to prevent retries on app errors
    // Log for manual investigation
  }

  return new Response("OK", { status: 200 });
}

// Subscription ID lives in different places depending on event type
function extractSubscriptionId(event: any): string | null {
  return (
    event.payload?.subscription?.entity?.id ||
    event.payload?.payment?.entity?.subscription_id ||
    event.payload?.invoice?.entity?.subscription_id ||
    null
  );
}