Razorpay Webhook

Handle payment events from Razorpay payment gateway

POST /razorpay

Razorpay Webhook

cURL

curl --request POST \
  --url https://api.example.com/razorpay

Overview

This webhook endpoint receives payment events from Razorpay. It serves as a reliable fallback mechanism to complete course enrollments even if the frontend verification fails due to network issues or browser closures.

This endpoint ensures that successful payments always result in course enrollment, regardless of client-side failures.

Authentication

Webhook Signature Verification

Razorpay uses HMAC SHA-256 signatures to verify webhook authenticity. The signature is computed over the raw request body bytes.

Required Header:

• x-razorpay-signature: HMAC SHA-256 signature of the raw request body

Verification Process:

const signature = req.headers['x-razorpay-signature']
const rawBody = req.body // Must be raw Buffer, not parsed JSON

const expectedSignature = crypto
  .createHmac('sha256', process.env.RAZORPAY_WEBHOOK_SECRET)
  .update(rawBody)
  .digest('hex')

if (!crypto.timingSafeEqual(
  Buffer.from(expectedSignature), 
  Buffer.from(signature)
)) {
  throw new Error('Invalid signature')
}

The request body MUST be kept as a raw Buffer for signature verification. Parsing to JSON before verification will cause signature mismatch.

Security Implementation Details

1. Raw Body Requirement: The endpoint uses express.raw() middleware to preserve the exact bytes sent by Razorpay
2. Timing-Safe Comparison: Uses crypto.timingSafeEqual() to prevent timing attacks
3. Secret Storage: Webhook secret is stored in RAZORPAY_WEBHOOK_SECRET environment variable

Event Types

payment.captured

Fired when a payment is successfully captured by Razorpay.

Action: Completes the purchase and enrolls the user in the course.

Payload Example:

{
  "event": "payment.captured",
  "payload": {
    "payment": {
      "entity": {
        "id": "pay_abc123xyz",
        "amount": 49900,
        "currency": "INR",
        "status": "captured",
        "order_id": "order_xyz789",
        "method": "card",
        "notes": {
          "purchaseId": "65f1a2b3c4d5e6f7g8h9i0j1"
        },
        "created_at": 1678901234
      }
    }
  }
}

Key Fields:

• event: Event type identifier
• payload.payment.entity.id: Razorpay payment ID
• payload.payment.entity.notes.purchaseId: Internal SkillRise purchase ID

The purchaseId is stored in Razorpay’s notes field when creating the order. This links Razorpay payments to internal purchase records.

Request Format

Headers

Header	Type	Required	Description
x-razorpay-signature	string	Yes	HMAC SHA-256 signature of raw body
Content-Type	string	Yes	Must be application/json

Body

{
  "event": "payment.captured",
  "payload": {
    "payment": {
      "entity": {
        "id": "string",
        "amount": 0,
        "currency": "string",
        "status": "captured",
        "order_id": "string",
        "method": "string",
        "notes": {
          "purchaseId": "string"
        },
        "created_at": 0
      }
    }
  }
}

Response Format

Success Response

Status Code: 200 OK

{
  "received": true
}

Returned for all successfully processed webhooks, regardless of whether the payment was handled.

Error Response

Status Code: 400 Bad Request

{
  "error": "Invalid Razorpay webhook signature"
}

Returned when signature verification fails.

Processing Logic

Payment Completion Flow

1. Signature Verification: Verify the webhook is from Razorpay
2. Parse Event: Convert raw body to JSON after verification
3. Check Event Type: Process only payment.captured events
4. Extract IDs: Get purchaseId from notes and paymentId from entity
5. Complete Purchase: Call completePurchase(purchaseId, paymentId) service
6. Acknowledge: Return success response

Idempotency

The completePurchase service handles duplicate webhook deliveries:

• If the purchase is already completed, the operation is idempotent
• Razorpay may retry webhook delivery, so duplicate events are handled gracefully

Event Filtering

• Only payment.captured events trigger purchase completion
• Other event types are acknowledged but not processed
• Missing purchaseId or paymentId is silently ignored

Error Handling

Signature Validation Errors

Causes:

• Missing x-razorpay-signature header
• Signature mismatch (tampered payload or wrong secret)

Response: 400 Bad Request with error message

Razorpay Behavior: Will retry webhook delivery with exponential backoff

Missing Data

Causes:

• purchaseId not present in payment notes
• paymentId missing from payment entity

Response: 200 OK with {"received": true}

Behavior: Event is acknowledged to prevent retries, but no action is taken

Database Errors

If completePurchase() throws an error:

• Error propagates and causes webhook to fail
• Razorpay will retry the webhook
• Purchase completion will be attempted again

Security Best Practices

1. Raw Body Preservation: Never parse the request body before signature verification
2. Timing-Safe Comparison: Use crypto.timingSafeEqual() to prevent timing attacks
3. Secret Rotation: Periodically rotate RAZORPAY_WEBHOOK_SECRET
4. HTTPS Only: Configure Razorpay to only send webhooks to HTTPS endpoints
5. IP Whitelisting: Consider restricting access to Razorpay’s webhook IP addresses

Middleware Requirements

This endpoint requires special Express middleware configuration:

// Apply raw body parser for Razorpay webhook route
app.post('/razorpay', 
  express.raw({ type: 'application/json' }),
  razorpayWebhooks
)

// Use JSON parser for other routes
app.use(express.json())

If express.json() middleware runs before this route, signature verification will fail. Always apply express.raw() specifically to this route.

Configuration

Razorpay Dashboard Setup

1. Log into your Razorpay Dashboard
2. Navigate to Settings > Webhooks
3. Click Create New Webhook
4. Enter your endpoint URL: https://yourdomain.com/razorpay
5. Select events to subscribe to:
   • payment.captured
6. Set a strong secret and copy it
7. Save the webhook configuration

Environment Variables

RAZORPAY_WEBHOOK_SECRET=your_webhook_secret_here

Keep this secret secure and never commit it to version control. Use environment-specific secrets for development, staging, and production.

Fallback Architecture

This webhook serves as a critical fallback in the payment flow:

┌─────────────┐
│   User      │
│   Pays      │
└──────┬──────┘
       │
       v
┌─────────────────┐
│   Razorpay      │
│   Processes     │
└────┬──────┬─────┘
     │      │
     │      └──────────────────┐
     v                         v
┌─────────────┐      ┌──────────────────┐
│  Frontend   │      │  Webhook (This)  │
│  Verify     │      │  Fallback        │
└──────┬──────┘      └────────┬─────────┘
       │                      │
       v                      v
   ┌──────────────────────────────┐
   │   completePurchase()         │
   │   (Idempotent Service)       │
   └──────────────────────────────┘

Benefits:

• Reliability: Enrollment completes even if user closes browser
• Network Resilience: Works despite frontend connectivity issues
• Idempotency: Handles both frontend and webhook completion safely

Implementation Reference

Location: server/controllers/webhooks.js:64

export const razorpayWebhooks = async (req, res) => {
  const signature = req.headers['x-razorpay-signature']
  const rawBody = req.body // Raw Buffer, not parsed JSON
  
  // Verify HMAC signature
  const expectedSignature = crypto
    .createHmac('sha256', process.env.RAZORPAY_WEBHOOK_SECRET)
    .update(rawBody)
    .digest('hex')
  
  if (!signature || !crypto.timingSafeEqual(
    Buffer.from(expectedSignature),
    Buffer.from(signature)
  )) {
    return res.status(400).json({ 
      error: 'Invalid Razorpay webhook signature' 
    })
  }
  
  // Parse after verification
  const event = JSON.parse(rawBody.toString())
  
  if (event.event === 'payment.captured') {
    const payment = event.payload?.payment?.entity
    const purchaseId = payment?.notes?.purchaseId
    const paymentId = payment?.id
    
    if (purchaseId && paymentId) {
      await completePurchase(purchaseId, paymentId)
    }
  }
  
  res.json({ received: true })
}

Related Services

• completePurchase: server/services/payments/order.service.js - Handles purchase completion and enrollment
• Payment Verification: See frontend payment verification flow for the primary completion path