Skip to main content
The plugin exposes a single webhook endpoint that receives events from Razorpay. Every incoming event is verified with HMAC-SHA256, then matched to a callback you configured in the plugin options. Subscription-related events also update the local subscription row before your callback runs.

Event overview

Every callback also triggers onEvent(event) if you defined it.

Payment events

payment.authorized

Fired when a payment is authorized but not yet captured.
auth.ts

payment.captured

Fired when a payment is successfully captured.
auth.ts

payment.failed

Fired when a payment attempt fails.
auth.ts

Order events

order.paid

Fired when an order is fully paid. This is the recommended event to use for order fulfillment instead of relying only on client-side verification.
auth.ts

Refund events

refund.created

Fired when a refund is initiated.
auth.ts

refund.processed

Fired when a refund is successfully processed.
auth.ts

refund.failed

Fired when a refund fails.
auth.ts

Invoice events

invoice.paid

Fired when an invoice is fully paid.
auth.ts

invoice.partially_paid

Fired when an invoice receives a partial payment.
auth.ts

invoice.expired

Fired when an invoice expires without payment.
auth.ts

Subscription events

Subscription webhooks update the local subscription row (status, period dates, counts) before firing your callback. This means subscription in the callback argument reflects the latest state.

subscription.authenticated

Fired when a subscription is authenticated (payment method added).
auth.ts

subscription.activated

Fired when a subscription becomes active.
auth.ts

subscription.charged

Fired when a subscription charge succeeds.
auth.ts

subscription.cancelled

Fired when a subscription is cancelled.
auth.ts

subscription.paused

Fired when a subscription is paused.
auth.ts

subscription.resumed

Fired when a paused subscription resumes.
auth.ts

subscription.halted

Fired when a subscription is halted, typically due to payment issues.
auth.ts

subscription.pending

Fired when a subscription enters a pending state.
auth.ts

subscription.completed

Fired when a subscription completes all billing cycles.
auth.ts

subscription.updated

Fired when a subscription is updated.
auth.ts

subscription.renewed

Fired when a subscription renews.
auth.ts

subscription.offer_updated

Fired when an offer is linked or unlinked from a subscription.
auth.ts

Global event handler

Define onEvent to receive every webhook event regardless of type. It runs before the specific callback.
auth.ts

Webhook setup

Configure the webhook URL in the Razorpay Dashboard under Account & Settings > Webhooks. The plugin endpoint follows the auth base path convention, typically https://your-domain.com/api/auth/razorpay/webhook.
Confirm the exact webhook path in your server by checking the plugin’s registered endpoints. If requests return 404, verify the path matches your auth handler mount point.
Set the same secret you pass as razorpayWebhookSecret in the plugin options, and select the events you want to receive.