Receive real-time payment notifications and updates with ZenPay Webhooks.
Webhooks allow ZenPay to send real-time notifications to your application when events occur, such as successful payments, refunds, or subscription updates. This enables your application to take appropriate actions automatically in response to these events.
Follow these steps to integrate ZenPay webhooks with your application:
First, create an endpoint on your server that will receive webhook events from ZenPay. This endpoint should be publicly accessible and respond with a 2xx status code.
// Express.js example
app.post('/webhooks/zenpay', express.raw({type: 'application/json'}), (req, res) => {
const signature = req.headers['zenpay-signature'];
try {
const event = zenpay.webhooks.constructEvent(
req.body,
signature,
process.env.WEBHOOK_SECRET
);
// Handle the event
switch (event.type) {
case 'payment.succeeded':
// Handle successful payment
break;
case 'payment.failed':
// Handle failed payment
break;
// ... handle other event types
default:
console.log(`Unhandled event type ${event.type}`);
}
res.status(200).send();
} catch (err) {
console.log(`Webhook error: ${err.message}`);
res.status(400).send(`Webhook Error: ${err.message}`);
}
});Go to the ZenPay Dashboard and navigate to Developers → Webhooks. Add your endpoint URL and select the events you wish to receive.
Screenshot of webhook setup in the dashboard
ZenPay signs webhook events it sends to your endpoints by including a signature in the zenpay-signature header. Verify this signature to ensure the event was sent by ZenPay and not by a third party.
# Python example
@app.route('/webhooks/zenpay', methods=['POST'])
def handle_webhook():
payload = request.data
sig_header = request.headers.get('zenpay-signature')
try:
event = zenpay.Webhook.construct_event(
payload, sig_header, webhook_secret
)
# Handle the event...
return '', 200
except ValueError as e:
# Invalid payload
return '', 400
except zenpay.error.SignatureVerificationError as e:
# Invalid signature
return '', 400Use the ZenPay Dashboard to send test events to your endpoint. This helps you verify that your integration works correctly before going live with real payments.
ZenPay sends events for various actions and state changes. Here are the most common events you might want to handle:
Sent when a payment is successfully processed and confirmed.
Sent when a payment attempt fails for any reason.
Sent when a payment is refunded, either partially or fully.
Sent when a payment is created but waiting for confirmation.
Sent when a customer completes the checkout process.
Sent when a new subscription is created.
Return a 2xx status code immediately before processing the webhook event. If ZenPay doesn't receive a 2xx response within 10 seconds, it will retry the webhook.
Always verify webhook signatures to ensure that events are coming from ZenPay and not from a malicious third party.
Design your webhook handler to be idempotent, as the same webhook event might be sent multiple times due to network issues or retry attempts.
Webhook events might arrive out of order or in parallel. Make sure your application can handle concurrent webhook requests correctly.