Webhooks

Get real-time notifications about events in your ZenPays account. Build responsive applications with our secure webhook system.

Powerful Webhook Features

Enterprise-grade webhook infrastructure built for scale and reliability

Secure Delivery

All webhooks are signed with HMAC-SHA256 for verification

Automatic Retries

Failed webhooks are retried with exponential backoff

Real-time Events

Events are delivered within seconds of occurrence

High Throughput

Handle thousands of events per second reliably

Available Events

Subscribe to the events that matter to your business

payment.successHigh

Triggered when a payment is successfully processed

Category: Payments
payment.failedHigh

Triggered when a payment fails

Category: Payments
refund.processedMedium

Triggered when a refund is successfully processed

Category: Refunds
subscription.createdMedium

Triggered when a new subscription is created

Category: Subscriptions
account.verifiedLow

Triggered when KYC verification is completed

Category: Accounts
payout.completedHigh

Triggered when a payout is successfully completed

Category: Payouts

Example Webhook Payload

{
  "id": "wh_1234567890abcdef",
  "object": "webhook_event",
  "api_version": "2023-12-01",
  "created": 1703123456,
  "data": {
    "object": {
      "id": "pay_9876543210fedcba",
      "object": "payment",
      "amount": 50000,
      "currency": "INR",
      "status": "succeeded",
      "payment_method": "upi",
      "description": "Test payment",
      "metadata": {
        "order_id": "ORD-2023-001"
      }
    }
  },
  "livemode": false,
  "pending_webhooks": 1,
  "request": {
    "id": "req_abcdef1234567890",
    "idempotency_key": null
  },
  "type": "payment.succeeded"
}

Webhook Verification

const crypto = require('crypto');
const express = require('express');

const app = express();
app.use(express.raw({ type: 'application/json' }));

app.post('/webhook', (req, res) => {
  const sig = req.headers['zenpays-signature'];
  const payload = req.body;
  const endpointSecret = 'whsec_your_webhook_secret';

  let event;

  try {
    const expectedSig = crypto
      .createHmac('sha256', endpointSecret)
      .update(payload, 'utf8')
      .digest('hex');

    if (sig !== expectedSig) {
      console.log('⚠️  Webhook signature verification failed.');
      return res.status(400).send('Webhook Error: Invalid signature');
    }

    event = JSON.parse(payload);
  } catch (err) {
    console.log('⚠️  Webhook payload error:', err.message);
    return res.status(400).send('Webhook Error: ' + err.message);
  }

  // Handle the event
  switch (event.type) {
    case 'payment.succeeded':
      console.log('💰 Payment succeeded:', event.data.object);
      break;
    case 'payment.failed':
      console.log('❌ Payment failed:', event.data.object);
      break;
    default:
      console.log('Unhandled event type:', event.type);
  }

  res.json({ received: true });
});

Best Practices

Follow these guidelines for optimal webhook implementation

Always Verify Signatures

Verify webhook signatures to ensure authenticity and prevent replay attacks.

Respond Quickly

Return 2xx status codes within 10 seconds to avoid retries.

Handle Failures Gracefully

Implement proper error handling and logging for failed webhook processing.

Design for Idempotency

Process duplicate events safely by implementing idempotent operations.

Use HTTPS Endpoints

Only use HTTPS endpoints to ensure secure webhook delivery.

Monitor Performance

Track webhook delivery times and success rates for optimization.

Start Using Webhooks Today

Configure your first webhook endpoint and start receiving real-time notifications.

View Documentation