> ## Documentation Index
> Fetch the complete documentation index at: https://better-auth-razorpay.amankushwaha.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhook endpoint

> Receive, verify, and handle Razorpay webhook events through the plugin endpoint.

The plugin exposes a single webhook endpoint that receives event notifications from Razorpay. Configure this endpoint in the Razorpay Dashboard so Razorpay can send events such as `payment.captured`, `order.paid`, and `subscription.activated`.

## Endpoint path

The webhook handler follows the plugin's path convention under your Better Auth mount point:

```text theme={null}
POST https://your-domain.com/api/auth/razorpay/webhook
```

> [!NOTE]
>
> Confirm the exact path in your server if requests return `404`. You can inspect the plugin's registered endpoints in your framework's route logs or by listing Better Auth routes.

## Headers

Razorpay sends the webhook signature in a request header:

**x-razorpay-signature** `string` *required*

HMAC-SHA256 hex digest of the raw request body, computed with your webhook secret.

The endpoint also relies on standard `Content-Type: application/json` headers from Razorpay.

## Verification

The plugin verifies the signature using `razorpayWebhookSecret` from your plugin options. It computes an HMAC-SHA256 of the raw request body and compares it with the header value using a timing-safe comparison.

```ts theme={null}
import { razorpay } from "@amank-root/better-auth-razorpay";

export const auth = betterAuth({
  plugins: [
    razorpay({
      keyId: process.env.RAZORPAY_KEY_ID!,
      keySecret: process.env.RAZORPAY_KEY_SECRET!,
      razorpayWebhookSecret: process.env.RAZORPAY_WEBHOOK_SECRET!,
    }),
  ],
});
```

If verification fails, the endpoint returns an error without invoking your callbacks.

## Responses and errors

| Situation | Response |
| - | - |
| Signature verified and handler succeeds | `200 OK` |
| Missing `x-razorpay-signature` header | `BAD_REQUEST` `WEBHOOK_SIGNATURE_NOT_FOUND` |
| `razorpayWebhookSecret` not configured | `INTERNAL_SERVER_ERROR` `WEBHOOK_SECRET_NOT_FOUND` |
| Signature does not match | `BAD_REQUEST` `FAILED_TO_VERIFY_WEBHOOK` |
| Handler throws | `INTERNAL_SERVER_ERROR` `WEBHOOK_ERROR` |

## Supported events

The plugin handles the following Razorpay events and routes each to its corresponding callback. All events also invoke the top-level `onEvent` handler if you provide one.

| Event | Callback |
| - | - |
| `payment.authorized` | `onPaymentAuthorized` |
| `payment.captured` | `onPaymentCaptured` |
| `payment.failed` | `onPaymentFailed` |
| `order.paid` | `onOrderPaid` |
| `refund.created` | `onRefundCreated` |
| `refund.processed` | `onRefundProcessed` |
| `refund.failed` | `onRefundFailed` |
| `invoice.paid` | `onInvoicePaid` |
| `invoice.partially_paid` | `onInvoicePartiallyPaid` |
| `invoice.expired` | `onInvoiceExpired` |
| `subscription.authenticated` | `onSubscriptionAuthenticated` |
| `subscription.activated` | `onSubscriptionActivated` |
| `subscription.charged` | `onSubscriptionCharged` |
| `subscription.cancelled` | `onSubscriptionCancelled` |
| `subscription.paused` | `onSubscriptionPaused` |
| `subscription.resumed` | `onSubscriptionResumed` |
| `subscription.halted` | `onSubscriptionHalted` |
| `subscription.pending` | `onSubscriptionPending` |
| `subscription.completed` | `onSubscriptionCompleted` |
| `subscription.updated` | `onSubscriptionUpdated` |
| `subscription.renewed` | `onSubscriptionRenewed` |
| `subscription.offer_updated` | `onSubscriptionOfferUpdated` |

Subscription webhooks update the local `subscription` table (status, period dates, counts) before your callbacks fire.

See [Webhook events](https://better-auth-razorpay.amankushwaha.dev/reference/webhook-events.md) for more detail on each event and payload shape.

## Local testing

Because Razorpay can only deliver webhooks to a public HTTPS URL, use a tunnel for local development:

```bash theme={null}
# Using ngrok
ngrok http 3000
```

Set the Razorpay Dashboard webhook URL to the ngrok HTTPS address plus the endpoint path, for example `https://abc123.ngrok.io/api/auth/razorpay/webhook`. Choose the events you want to receive and set the same secret you use in `razorpayWebhookSecret`.

## Example configuration

```ts theme={null}
import { betterAuth } from "better-auth";
import { razorpay } from "@amank-root/better-auth-razorpay";

export const auth = betterAuth({
  plugins: [
    razorpay({
      keyId: process.env.RAZORPAY_KEY_ID!,
      keySecret: process.env.RAZORPAY_KEY_SECRET!,
      razorpayWebhookSecret: process.env.RAZORPAY_WEBHOOK_SECRET!,
      onEvent: async (event) => {
        console.log("Razorpay event:", event.event);
      },
      onPaymentCaptured: async ({ event, payment }) => {
        console.log("Payment captured:", payment.id);
      },
      onSubscriptionActivated: async ({ event, razorpaySubscription, subscription, plan }) => {
        console.log("Subscription activated:", subscription.id, "on plan", plan.name);
      },
    }),
  ],
});
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.