Webhooks Overview

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?

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

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 for signature verification.

Webhook Payload

Every webhook delivery includes:

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

Webhook Limits

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:

Auto-Disable

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

Dashboard Features

From 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 to expose your local server:

ngrok http 3000

Next Steps

• Events Reference - All available event types
• Webhook Security - Verify webhook signatures