Razorpay Connection Webhook

POST

webhooks

razorpay

{connID}

Razorpay webhook receiver (per-connection, BYO)

curl --request POST \
  --url https://billing.example.com/webhooks/razorpay/{connID} \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --header 'X-Razorpay-Signature: <x-razorpay-signature>' \
  --data '{}'

import requests

url = "https://billing.example.com/webhooks/razorpay/{connID}"

payload = {}
headers = {
    "X-Razorpay-Signature": "<x-razorpay-signature>",
    "Authorization": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'X-Razorpay-Signature': '<x-razorpay-signature>',
    Authorization: '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({})
};

fetch('https://billing.example.com/webhooks/razorpay/{connID}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://billing.example.com/webhooks/razorpay/{connID}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: <api-key>",
    "Content-Type: application/json",
    "X-Razorpay-Signature: <x-razorpay-signature>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://billing.example.com/webhooks/razorpay/{connID}"

	payload := strings.NewReader("{}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-Razorpay-Signature", "<x-razorpay-signature>")
	req.Header.Add("Authorization", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://billing.example.com/webhooks/razorpay/{connID}")
  .header("X-Razorpay-Signature", "<x-razorpay-signature>")
  .header("Authorization", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://billing.example.com/webhooks/razorpay/{connID}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-Razorpay-Signature"] = '<x-razorpay-signature>'
request["Authorization"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{}"

response = http.request(request)
puts response.read_body

{
  "status": "ok",
  "reason": "<string>"
}

{
  "error": {
    "code": "validation_failed",
    "message": "<string>"
  }
}

{
  "error": {
    "code": "validation_failed",
    "message": "<string>"
  }
}

{
  "error": {
    "code": "validation_failed",
    "message": "<string>"
  }
}

Per-connection variant of the Razorpay webhook receiver for workspaces that connected their own Razorpay account with Connect a Gateway. The event is verified with that connection’s own webhook secret (resolved from connID) before the payload is trusted. Invoice, refund and virtual-account events are bound to the connection’s workspace; token.confirmed is not (see below). Event handling is otherwise identical to the platform receiver.

Each connection has its own URL. Read webhook_path from List Gateway Connections (for example /webhooks/razorpay/{connID}), append it to https://api.recurso.dev, and register that URL in the Razorpay Dashboard under Settings > Webhooks using the webhook_secret you supplied when connecting, or set later with Set Gateway Webhook Secret. A connection without a webhook secret cannot verify deliveries and rejects them.

Parameters

Parameter	Type	Required	Description
`connID`	string (UUID, path)	Yes	The workspace’s Razorpay gateway-connection id.
`X-Razorpay-Signature`	string (header)	Yes	HMAC-SHA256 hex signature of the raw request body, computed with the connection’s webhook secret.
`X-Razorpay-Event-Id`	string (header)	No	Razorpay’s event id, used as the deduplication key. When absent, a SHA-256 hash of the signed body is used instead.

Request Body

The raw Razorpay event payload. The event field selects the handler:

Event	Effect
`payment.captured`, `order.paid`	Settles the invoice named in `notes.invoice_id` (`open` → `paid`), stores the `pay_*` id for later refunds, and records the dunning success.
`payment.failed`	Marks the invoice in `notes.invoice_id` `past_due`, records the dunning failure, and triggers the dunning campaign.
`refund.processed`, `refund.failed`	Advances the credit note that owns the refund (`pending` → `processed` or `refund_failed`).
`token.confirmed`	Activates the UPI mandate authorized by the customer.
`virtual_account.credited`	Reconciles an offline payment against the virtual account it landed in.

Any other event is acknowledged with status: "ignored". An invoice, refund or virtual account that belongs to a different workspace than the connection is never applied: an invoice is acknowledged as ignored with reason unknown invoice_id, while a refund or virtual account is acknowledged with status: "ok" and no reason, exactly as if it had been applied. token.confirmed resolves the mandate by its Razorpay token id alone and is not checked against the connection’s workspace.

Example Request

Razorpay sends a POST request with event data:

curl -X POST https://api.recurso.dev/webhooks/razorpay/7c9e6679-7425-40de-944b-e07fc1f90ae7 \
  -H "Content-Type: application/json" \
  -H "X-Razorpay-Signature: 3f1a9c0e7b2d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8091a2b3c4d5e6f708192a3b" \
  -H "X-Razorpay-Event-Id: Rzp9ABCDEF123456" \
  -d '{
    "entity": "event",
    "event": "payment.captured",
    "payload": {
      "payment": {
        "entity": {
          "id": "pay_RzpABC123",
          "amount": 249900,
          "currency": "INR",
          "status": "captured",
          "order_id": "order_RzpDEF456",
          "notes": {
            "invoice_id": "1c1b3a5e-4d7f-4c1a-9f2e-6b8d0a3c5e71"
          }
        }
      }
    }
  }'

Response

Returns 200 OK on successful processing. A payment.captured or order.paid whose invoice_id matches no invoice is acknowledged as ignored; a payment.failed whose invoice_id matches no invoice is treated as an error and returns 500, so Razorpay keeps redelivering it.

{
  "status": "ok"
}

When the event is acknowledged but deliberately not applied, reason says why:

{
  "status": "ignored",
  "reason": "unknown invoice_id"
}

Fields

Field	Type	Description
`status`	string	`ok` when the event was applied (or, for a refund or virtual account owned by another workspace, silently not applied), `ignored` when it was acknowledged without side effects. A redelivery of an event that was already applied returns `duplicate ignored`.
`reason`	string	Present on some ignored events: `no invoice_id`, `invalid invoice_id`, `unknown invoice_id` (also used for an invoice owned by another workspace), `no refund_id`, `unknown refund_id`, `no token_id`, or `no va_id`. Absent for unhandled event types.

Deduplication keys on X-Razorpay-Event-Id. When the header is missing, the delivery is deduplicated on a hash of the signed body instead, so a byte-identical replay is still ignored. An event is only recorded as processed after a 2xx response; a delivery that fails with 5xx is retried by Razorpay and reprocessed.

Errors

Status	Code	When	Fix
`400`	`validation_failed`	`connID` in the path is not a UUID	Use the connection’s `webhook_path` from List Gateway Connections
`400`	`validation_failed`	Request body could not be read, is not valid JSON, or the event-specific payload (token, refund, virtual account) cannot be parsed	Check the delivery in the Razorpay Dashboard; Recurso expects the raw event payload
`401`	`unauthorized`	`X-Razorpay-Signature` is missing or does not match the HMAC-SHA256 of the raw body under this connection’s secret	Make sure the secret registered in Razorpay matches the connection’s `webhook_secret`
`404`	`not_found`	No active Razorpay connection has this id (a missing, disconnected, or non-Razorpay connection all return 404)	Reconnect the gateway and register the new `webhook_path`
`500`	`internal_error`	The invoice could not be loaded; settling, reconciling, or advancing the refund failed; or a `payment.failed` names an `invoice_id` that matches no invoice	Razorpay retries the delivery; the event is not recorded as processed until it succeeds
`503`	`internal_error`	The connection has no webhook secret (the receiver fails closed), per-connection webhooks are not configured on the API, or the inbound-webhook dedup store is unavailable	Store the secret with Set Gateway Webhook Secret (the connection id and `webhook_path` stay the same); otherwise let Razorpay retry

Errors use the standard envelope — see Errors.

Authorizations

Authorization

string

header

required

Headers

X-Razorpay-Signature

string

required

HMAC-SHA256 signature of the raw request body.

Path Parameters

connID

string<uuid>

required

The tenant's Razorpay gateway-connection id.

Body

application/json

Raw Razorpay event payload.

Response

Event processed (or deliberately ignored).

status

enum<string>

Available options:

ok,

ignored

reason

string

Razorpay webhook receiver (per-connection, BYO)

curl --request POST \
  --url https://billing.example.com/webhooks/razorpay/{connID} \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --header 'X-Razorpay-Signature: <x-razorpay-signature>' \
  --data '{}'

import requests

url = "https://billing.example.com/webhooks/razorpay/{connID}"

payload = {}
headers = {
    "X-Razorpay-Signature": "<x-razorpay-signature>",
    "Authorization": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'X-Razorpay-Signature': '<x-razorpay-signature>',
    Authorization: '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({})
};

fetch('https://billing.example.com/webhooks/razorpay/{connID}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://billing.example.com/webhooks/razorpay/{connID}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: <api-key>",
    "Content-Type: application/json",
    "X-Razorpay-Signature: <x-razorpay-signature>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://billing.example.com/webhooks/razorpay/{connID}"

	payload := strings.NewReader("{}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-Razorpay-Signature", "<x-razorpay-signature>")
	req.Header.Add("Authorization", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://billing.example.com/webhooks/razorpay/{connID}")
  .header("X-Razorpay-Signature", "<x-razorpay-signature>")
  .header("Authorization", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://billing.example.com/webhooks/razorpay/{connID}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-Razorpay-Signature"] = '<x-razorpay-signature>'
request["Authorization"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{}"

response = http.request(request)
puts response.read_body

{
  "status": "ok",
  "reason": "<string>"
}

{
  "error": {
    "code": "validation_failed",
    "message": "<string>"
  }
}

{
  "error": {
    "code": "validation_failed",
    "message": "<string>"
  }
}

{
  "error": {
    "code": "validation_failed",
    "message": "<string>"
  }
}

Getting Started

Core

Billing & Invoicing

Revenue & Finance

Growth & Recovery

Compliance (India)

Platform

Customer Portal API

Razorpay Connection Webhook

Parameters

Request Body

Example Request

Response

Fields

Errors

Authorizations

Headers

Path Parameters

Body

Response

​Parameters

​Request Body

​Example Request

​Response

​Fields

​Errors

Authorizations

Headers

Path Parameters

Body

Response

Parameters

Request Body

Example Request

Response

Fields

Errors