debug

Razorpay Debugging Guide

Common issues and their solutions, organized by symptom.

Webhook Not Firing

Check these in order:

1. Webhook URL registered: Dashboard → Settings → Webhooks → Verify URL is correct
2. HTTPS required: Razorpay won't call HTTP endpoints (except localhost in test mode)
3. Events enabled: Check which events are checked in webhook settings
4. Response timeout: Razorpay expects 2xx within 5 seconds. If your handler takes longer, it times out and retries.
5. Check webhook logs: Dashboard → Settings → Webhooks → Click on webhook → View delivery attempts

Test locally with ngrok:

ngrok http 3000
# Copy the https URL → Register as webhook URL in Razorpay Dashboard

Signature Verification Failing

Most common causes:

1. Using wrong secret: Webhook signature uses RAZORPAY_WEBHOOK_SECRET. Payment verification uses RAZORPAY_KEY_SECRET. They are DIFFERENT values.

2. Parsing body as JSON first: Signature is computed on the RAW string body. If you parse to JSON and re-stringify, whitespace changes break the signature.

   // WRONG
   const body = await request.json();
   const raw = JSON.stringify(body);  // May differ from original!
   
   // CORRECT
   const raw = await request.text();
   const body = JSON.parse(raw);
   

3. Invoice signature format wrong: Order flow and invoice flow have different signature payloads:

   Order:   HMAC(secret, "order_id|payment_id")
   Invoice: HMAC(secret, "invoice_id|receipt|status|payment_id")
   

4. Optional fields undefined: Invoice receipt and status may be undefined. Use ?? "":

   const payload = `${invoiceId}|${receipt ?? ""}|${status ?? ""}|${paymentId}`;
   

Duplicate Webhook Events

Symptom: Same subscription activated twice, duplicate GST invoices, double access grants.

Root cause: Razorpay uses at-least-once delivery. If your handler doesn't return 200 within 5 seconds, it retries.