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.success
HighTriggered when a payment is successfully processed
Category: Paymentspayment.failed
HighTriggered when a payment fails
Category: Paymentsrefund.processed
MediumTriggered when a refund is successfully processed
Category: Refundssubscription.created
MediumTriggered when a new subscription is created
Category: Subscriptionsaccount.verified
LowTriggered when KYC verification is completed
Category: Accountspayout.completed
HighTriggered when a payout is successfully completed
Category: PayoutsExample 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.