---
title: Webhooks Overview
description: Receive real-time notifications for transaction events
---

Webhooks let you receive real-time notifications when events happen in your account. Instead of polling the API for status updates, webhooks push data to your server automatically.

## Why Use Webhooks?

| Without Webhooks       | With Webhooks                |
| ---------------------- | ---------------------------- |
| Poll API repeatedly    | Receive instant updates      |
| Waste API requests     | Only receive relevant events |
| Delayed status updates | Real-time notifications      |
| Complex polling logic  | Simple event handlers        |

## How Webhooks Work

1. You create a webhook endpoint in your dashboard
2. You subscribe to specific events (or all events)
3. When an event occurs, we send an HTTP POST to your endpoint
4. Your server processes the payload and returns a 2xx response
5. If delivery fails, we retry automatically

## Quick Setup

### 1. Create an Endpoint

Go to [Settings > Webhooks](https://my.rizpay.app/settings/webhooks) and create a new webhook:

- **URL**: Your HTTPS endpoint (e.g., `https://yourapp.com/webhooks/rizpay`)
- **Environment**: Production or Sandbox
- **Events**: Select events or subscribe to all (`*`)

### 2. Handle the Webhook

```javascript
const express = require("express");
const app = express();

app.post("/webhooks/rizpay", express.json(), (req, res) => {
  const event = req.body;

  console.log(`Received ${event.type} event`);

  switch (event.type) {
    case "transaction.successful":
      handleSuccessfulTransaction(event.data.object);
      break;
    case "transaction.failed":
      handleFailedTransaction(event.data.object);
      break;
    // Handle other events...
  }

  // Always return 200 to acknowledge receipt
  res.status(200).send("OK");
});
```

### 3. Verify the Signature

See [Webhook Security](/docs/webhooks/security) for signature verification.

## Webhook Payload

Every webhook delivery includes:

```json
{
  "id": "evt_abc123xyz",
  "type": "transaction.successful",
  "api_version": "1.0.0",
  "created_at": "2024-01-15T10:30:00Z",
  "data": {
    "object": {
      // Event-specific data
    }
  }
}
```

| Field         | Description                                                |
| ------------- | ---------------------------------------------------------- |
| `id`          | Unique event identifier                                    |
| `type`        | Event type (see [Events Reference](/docs/webhooks/events)) |
| `api_version` | API version that generated the event                       |
| `created_at`  | When the event occurred                                    |
| `data.object` | The object that triggered the event                        |

## Webhook Limits

| Environment | Max Webhooks |
| ----------- | ------------ |
| Sandbox     | 1            |
| Production  | 3            |

## Delivery Behavior

### Success

We consider delivery successful when your endpoint returns a 2xx status code within 30 seconds.

### Retries

If delivery fails (timeout or non-2xx response), we retry with increasing delays:

| Attempt   | Delay      |
| --------- | ---------- |
| 1         | Immediate  |
| 2         | 1 minute   |
| 3         | 5 minutes  |
| 4         | 30 minutes |
| 5         | 2 hours    |
| 6 (final) | 24 hours   |

### Auto-Disable

After 5 consecutive failures, the webhook is automatically disabled. You can re-enable it from the dashboard.

## Dashboard Features

From [Settings > Webhooks](https://my.rizpay.app/settings/webhooks), you can:

- **Create/Edit webhooks** - Configure URL and events
- **Send test payloads** - Test your endpoint
- **View delivery history** - See all deliveries with response details
- **Enable/Disable** - Toggle webhooks without deleting

## Best Practices

1. **Return 200 quickly** - Process webhooks asynchronously if needed
2. **Verify signatures** - Always verify webhook authenticity
3. **Handle duplicates** - Use the event `id` for idempotency
4. **Log everything** - Keep records for debugging
5. **Use HTTPS** - Webhook URLs must be HTTPS

## Testing Webhooks

### Sandbox Webhooks

Create a sandbox webhook to receive test events without affecting production.

### Test Payloads

Use the "Send Test" button in the dashboard to send a sample payload to your endpoint.

### Local Development

Use tools like [ngrok](https://ngrok.com) to expose your local server:

```bash
ngrok http 3000
```

## Next Steps

- [Events Reference](/docs/webhooks/events) - All available event types
- [Webhook Security](/docs/webhooks/security) - Verify webhook signatures