> ## 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 events

> Complete list of Razorpay webhook events handled by the plugin, their callbacks, and what the plugin does for each event.

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

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

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

## Payment events

### `payment.authorized`

Fired when a payment is authorized but not yet captured.

```ts auth.ts theme={null}
razorpay({
  onPaymentAuthorized: ({ event, payment }) => {
    console.log("Payment authorized:", payment.id);
  },
});
```

### `payment.captured`

Fired when a payment is successfully captured.

```ts auth.ts theme={null}
razorpay({
  onPaymentCaptured: ({ event, payment }) => {
    console.log("Payment captured:", payment.id);
  },
});
```

### `payment.failed`

Fired when a payment attempt fails.

```ts auth.ts theme={null}
razorpay({
  onPaymentFailed: ({ event, payment }) => {
    console.log("Payment failed:", payment.id);
  },
});
```

## 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.

```ts auth.ts theme={null}
razorpay({
  onOrderPaid: ({ event, order }) => {
    console.log("Order paid:", order.id);
    // Fulfill the order here
  },
});
```

## Refund events

### `refund.created`

Fired when a refund is initiated.

```ts auth.ts theme={null}
razorpay({
  onRefundCreated: ({ event, refund }) => {
    console.log("Refund created:", refund.id);
  },
});
```

### `refund.processed`

Fired when a refund is successfully processed.

```ts auth.ts theme={null}
razorpay({
  onRefundProcessed: ({ event, refund }) => {
    console.log("Refund processed:", refund.id);
  },
});
```

### `refund.failed`

Fired when a refund fails.

```ts auth.ts theme={null}
razorpay({
  onRefundFailed: ({ event, refund }) => {
    console.log("Refund failed:", refund.id);
  },
});
```

## Invoice events

### `invoice.paid`

Fired when an invoice is fully paid.

```ts auth.ts theme={null}
razorpay({
  onInvoicePaid: ({ event, invoice }) => {
    console.log("Invoice paid:", invoice.id);
  },
});
```

### `invoice.partially_paid`

Fired when an invoice receives a partial payment.

```ts auth.ts theme={null}
razorpay({
  onInvoicePartiallyPaid: ({ event, invoice }) => {
    console.log("Invoice partially paid:", invoice.id);
  },
});
```

### `invoice.expired`

Fired when an invoice expires without payment.

```ts auth.ts theme={null}
razorpay({
  onInvoiceExpired: ({ event, invoice }) => {
    console.log("Invoice expired:", invoice.id);
  },
});
```

## 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).

```ts auth.ts theme={null}
razorpay({
  subscription: {
    enabled: true,
    plans: [...],
    onSubscriptionAuthenticated: ({ event, razorpaySubscription, subscription }) => {
      console.log("Subscription authenticated:", subscription.id);
    },
  },
});
```

### `subscription.activated`

Fired when a subscription becomes active.

```ts auth.ts theme={null}
razorpay({
  subscription: {
    enabled: true,
    plans: [...],
    onSubscriptionActivated: ({ event, razorpaySubscription, subscription, plan }) => {
      console.log("Subscription activated:", subscription.id);
    },
  },
});
```

### `subscription.charged`

Fired when a subscription charge succeeds.

```ts auth.ts theme={null}
razorpay({
  subscription: {
    enabled: true,
    plans: [...],
    onSubscriptionCharged: ({ event, razorpaySubscription, subscription }) => {
      console.log("Subscription charged:", subscription.id);
    },
  },
});
```

### `subscription.cancelled`

Fired when a subscription is cancelled.

```ts auth.ts theme={null}
razorpay({
  subscription: {
    enabled: true,
    plans: [...],
    onSubscriptionCancelled: ({ event, razorpaySubscription, subscription }) => {
      console.log("Subscription cancelled:", subscription.id);
    },
  },
});
```

### `subscription.paused`

Fired when a subscription is paused.

```ts auth.ts theme={null}
razorpay({
  subscription: {
    enabled: true,
    plans: [...],
    onSubscriptionPaused: ({ event, razorpaySubscription, subscription }) => {
      console.log("Subscription paused:", subscription.id);
    },
  },
});
```

### `subscription.resumed`

Fired when a paused subscription resumes.

```ts auth.ts theme={null}
razorpay({
  subscription: {
    enabled: true,
    plans: [...],
    onSubscriptionResumed: ({ event, razorpaySubscription, subscription }) => {
      console.log("Subscription resumed:", subscription.id);
    },
  },
});
```

### `subscription.halted`

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

```ts auth.ts theme={null}
razorpay({
  subscription: {
    enabled: true,
    plans: [...],
    onSubscriptionHalted: ({ event, razorpaySubscription, subscription }) => {
      console.log("Subscription halted:", subscription.id);
    },
  },
});
```

### `subscription.pending`

Fired when a subscription enters a pending state.

```ts auth.ts theme={null}
razorpay({
  subscription: {
    enabled: true,
    plans: [...],
    onSubscriptionPending: ({ event, razorpaySubscription, subscription }) => {
      console.log("Subscription pending:", subscription.id);
    },
  },
});
```

### `subscription.completed`

Fired when a subscription completes all billing cycles.

```ts auth.ts theme={null}
razorpay({
  subscription: {
    enabled: true,
    plans: [...],
    onSubscriptionCompleted: ({ event, razorpaySubscription, subscription }) => {
      console.log("Subscription completed:", subscription.id);
    },
  },
});
```

### `subscription.updated`

Fired when a subscription is updated.

```ts auth.ts theme={null}
razorpay({
  subscription: {
    enabled: true,
    plans: [...],
    onSubscriptionUpdated: ({ event, razorpaySubscription, subscription }) => {
      console.log("Subscription updated:", subscription.id);
    },
  },
});
```

### `subscription.renewed`

Fired when a subscription renews.

```ts auth.ts theme={null}
razorpay({
  subscription: {
    enabled: true,
    plans: [...],
    onSubscriptionRenewed: ({ event, razorpaySubscription, subscription }) => {
      console.log("Subscription renewed:", subscription.id);
    },
  },
});
```

### `subscription.offer_updated`

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

```ts auth.ts theme={null}
razorpay({
  subscription: {
    enabled: true,
    plans: [...],
    onSubscriptionOfferUpdated: ({ event, razorpaySubscription, subscription }) => {
      console.log("Subscription offer updated:", subscription.id);
    },
  },
});
```

## Global event handler

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

```ts auth.ts theme={null}
razorpay({
  onEvent: (event) => {
    console.log("Received event:", event.event);
  },
});
```

## 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`.

> [!NOTE]
>
> 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.


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