Skip to main content
POST
Receive a Razorpay webhook delivery

Authorizations

Authorization
string
header
required

Caller API key issued by scripts/generate-api-key.ts. Sent as Authorization: Bearer . Verified against a stored SHA-256 hash in constant time by packages/api/src/auth/StaticKeyAuthenticator.ts. Required on every route except GET /health. See /api-reference/authentication.

Headers

X-Razorpay-Signature
string
required

hex(HMAC-SHA256(rawBody, RAZORPAY_WEBHOOK_SECRET))

X-Razorpay-Event-Id
string
required

Required once the signature has verified; a request missing it is rejected even with a valid signature.

Body

application/json

Request payload for POST /webhooks/razorpay — Razorpay's own webhook envelope, forwarded verbatim. Shape and fields vary by event type; this schema only documents the fields this route itself reads (event, payload.payment.entity.id, payload.refund.entity.id) for audit metadata extraction. The full payload is persisted as-is for later processing (M4b) and is not otherwise validated against this schema at runtime — signature verification (X-Razorpay-Signature) is what actually authenticates a request, not payload shape.

entity
string

Always "event" for a Razorpay webhook delivery.

Example:

"event"

event
string

Razorpay event type. Extracted into the pending-events store and audit trail when present.

Examples:

"refund.processed"

"payment.captured"

contains
string[]
payload
object
created_at
integer

Unix timestamp.

Response

Verified event accepted (fresh) or acknowledged (duplicate).

Response body for POST /webhooks/razorpay on a 200. "accepted" means this event id was fresh and has been persisted to the pending-events store. "acknowledged" means this event id had already been recorded (a replay/duplicate delivery) — it was not persisted or reprocessed again.

status
enum<string>
required
Available options:
accepted,
acknowledged