Skip to main content
Razorpay sends webhook events to your server when payments, orders, refunds, invoices, and subscriptions change state. The plugin exposes a webhook endpoint, verifies each request’s signature, keeps the local subscription table in sync, and calls the callbacks you configure. Use webhooks as the source of truth for fulfillment. Client-side verification tells you the checkout finished, but the order.paid and subscription.activated events confirm that Razorpay actually received the money.

How it works

  1. Razorpay sends a POST request with a JSON body and an x-razorpay-signature header.
  2. The plugin computes an HMAC-SHA256 of the raw body using razorpayWebhookSecret and compares it with the header using a timing-safe comparison.
  3. For subscription events, the plugin updates the matching local subscription row (status, billing period dates, and counts).
  4. The plugin calls the event-specific callback, such as onOrderPaid, and onEvent for every event.

Set up webhooks

1

Add the webhook secret to your environment

Choose a strong random string. You use the same value in Razorpay and in your server config.
.env
2

Configure the plugin

Pass the secret and the callbacks you need.
auth.ts
markOrderPaid and markRefundComplete stand in for your own application code.
3

Register the webhook in Razorpay

In the Razorpay Dashboard, open Account & Settings > Webhooks and add a webhook:
  • Webhook URL: https://your-domain.com/api/auth/razorpay/webhook
  • Secret: the value of RAZORPAY_WEBHOOK_SECRET
  • Active events: the events you handle (see Webhook events)
The URL follows the plugin’s path convention under your Better Auth base path (/api/auth). If Razorpay reports 404 responses, confirm the webhook endpoint path registered by the plugin in your server.
4

Test locally

Razorpay cannot reach localhost. Expose your dev server with a tunnel such as ngrok and use the public URL in the Razorpay Dashboard while in test mode.

Subscription callbacks

Subscription callbacks live inside the subscription options. The plugin updates the local subscription row before it calls them, so subscription reflects the new state.
auth.ts
See Webhook events for every event, its callback, and the payload shape.

Errors

Keep callbacks idempotent. Razorpay can deliver the same event more than once, so check whether you already fulfilled an order or granted access before doing it again.

Verify signatures yourself

If you process webhooks outside the plugin, use the exported helpers. See Signature utilities.

Webhook events

Every supported event and callback.

Webhook endpoint

Endpoint behavior, headers, and responses.