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
- Razorpay sends a
POSTrequest with a JSON body and anx-razorpay-signatureheader. - The plugin computes an HMAC-SHA256 of the raw body using
razorpayWebhookSecretand compares it with the header using a timing-safe comparison. - For subscription events, the plugin updates the matching local subscription row (status, billing period dates, and counts).
- The plugin calls the event-specific callback, such as
onOrderPaid, andonEventfor 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 thesubscription options. The plugin updates the local subscription row before it calls them, so subscription reflects the new state.
auth.ts
Errors
Verify signatures yourself
If you process webhooks outside the plugin, use the exported helpers. See Signature utilities.Related
Webhook events
Every supported event and callback.
Webhook endpoint
Endpoint behavior, headers, and responses.