Webhooks Overview

Webhooks allow you to receive real-time notifications about transaction events. Instead of polling for status updates, ZoPay will automatically send HTTP POST requests to your registered endpoint when events occur.

How Webhooks Work

1. Register a webhook endpoint in your dashboard (or via API) with your server URL
2. ZoPay generates a unique webhook secret (shown only once - save it securely!)
3. ZoPay sends HTTP POST requests to your endpoint when events occur
4. Your server verifies the webhook signature using the provided secret
5. Your server checks the delivery ID for idempotency (prevent duplicates)
6. Your server processes the event and updates your system
7. Your server returns a 200 OK response within 30 seconds

Supported Events

Important: You must subscribe to all 6 required events when registering a webhook endpoint. This ensures you receive all transaction notifications.

Key Features

• ✅ Real-time notifications for all transaction events
• ✅ HMAC signature verification for security
• ✅ Automatic retries with exponential backoff (6 attempts)
• ✅ Dead letter queue for failed deliveries
• ✅ Manual replay of failed webhooks
• ✅ Delivery logs and monitoring

Webhook Security

All webhooks include an HMAC-SHA256 signature in the X-Zo-Signature header. Always verify this signature before processing webhook payloads to ensure requests are from ZoPay.

For detailed signature verification instructions, see the Webhook Security page.

Retry Logic

If your server doesn't respond with HTTP 200-299, ZoPay will automatically retry the webhook delivery (up to 6 attempts):

After 6 failed attempts, the webhook is moved to the Dead Letter Queue (DLQ) where you can manually replay it after fixing the issue.

Best Practices

• Always verify signatures: Never process webhooks without signature verification - this is critical for security
• Use raw body for signature: Capture the raw request body before JSON parsing for signature verification
• Respond quickly: Return HTTP 200 within 30 seconds. Process webhooks asynchronously using a queue if needed.
• Implement idempotency: Use X-Zo-Delivery-Id header to prevent duplicate processing
• Handle duplicates: Webhooks may be delivered more than once. Always check delivery ID before processing.
• Check timestamps: Verify timestamp is within 5 minutes to prevent replay attacks
• Use HTTPS: Webhook URLs must use HTTPS in production (HTTP is only allowed for local testing)
• Store secrets securely: Never commit webhook secrets to code - use environment variables or secret management
• Log everything: Log all webhook deliveries for debugging and auditing
• Monitor deliveries: Regularly check webhook delivery status in the dashboard and set up alerts for failed webhooks
• Handle errors gracefully: Don't let processing errors crash your server
• Subscribe to all events: All 6 events are required when registering a webhook endpoint

Monitoring and Logging

It's important to monitor your webhook activity to ensure everything is working correctly:

What to Monitor

• Webhook Receipts: Track all incoming webhooks
• Success Rate: Monitor successful vs failed webhook processing
• Signature Verification: Track invalid signature attempts (security concern)
• Duplicate Deliveries: Monitor how often duplicate webhooks are received
• Response Times: Ensure responses are within 30 seconds
• Error Rates: Alert on high error rates

Webhook Status Indicators

Your webhook handler should track these statuses:

Logging Best Practices

• Log all receipts: Include delivery ID, event type, timestamp, status
• Store payloads: Keep payload data for troubleshooting (sanitize sensitive data)
• Track errors: Log full error context for debugging
• Set up alerts: Alert on security issues or high error rates
• Use persistent storage: Store logs in database or logging service (not just in-memory)

Production Checklist

Before going to production, ensure:

Next Steps

• Learn how to Register a Webhook Endpoint
• See all available Webhook Events
• Understand Webhook Security and Signature Verification
• View Your Webhook Endpoints in the dashboard