Webhooks
Learn how to set up and configure webhooks to receive real-time payment notifications from EximPe. This guide covers webhook setup, testing, and best practices for integration.
What are Webhooks?
Webhooks are real-time server-to-server (S2S) notifications that EximPe sends to your backend when important events occur. Unlike browser redirects that can be interrupted, webhooks ensure reliable delivery of payment status updates directly to your server.
Reliable Delivery
Notifications sent directly to your server with automatic retries
Real-time Updates
Instant notification of payment events as they happen
No User Dependency
Works even if customer closes the browser or loses connection
Secure Communication
Encrypted and signed for authenticity and data integrity
Supported Events
EximPe sends webhooks for these key events:
Payment Successful
When: Customer completes payment
Use Case: Update order status, send confirmation
Payment Failed
When: Payment attempt fails
Use Case: Retry payment, notify customer
Payment Refunded
When: Refund is processed
Use Case: Update inventory, notify customer
Merchant Approved
When: Merchant account activated
Use Case: Enable payment collection
Settlement Completed
When: Funds transferred to merchant
Use Case: Update accounting records
🛠️ Setup Guide
Step 1: Prepare Your Endpoint
Ensure your server has a public HTTPS URL accessible from the internet, a POST endpoint that can receive webhook data, 200 OK response capability, and support for application/json
.
Step 2: Configure Webhook URL
Dashboard Configuration (Recommended)
- Log into your EximPe Dashboard
- Navigate to Developer Section
- Enter your webhook URL
- Save configuration
- Whitelist EximPe IP addresses - Configure your firewall to only accept webhooks from EximPe’s IP ranges (found in Developer Section)
Manual Setup
- Contact EximPe Support with your webhook URL
- Provide your server’s IP address
- EximPe will whitelist your endpoint
- You’ll receive EximPe’s IP range for firewall configuration
- Whitelist EximPe IP addresses - Configure your firewall to only accept webhooks from EximPe’s IP ranges
Step 3: Test Your Integration
Log Requests
Log all incoming requests on your server to monitor webhook delivery
Test Payment
Make a test payment in sandbox environment to trigger webhooks
Verify Receipt
Verify webhook receipt and processing in your logs
Check Response
Ensure your endpoint returns 200 OK response codes
🔐 Security & Verification
EximPe signs each webhook with an HMAC signature to ensure authenticity:
Verification Steps
Extract the signature
Extract the signature from the X-Webhook-Signature header in the request
Get your API key
Get your Encryption key
Recreate the signature
Recreate the signature using HMAC-SHA256:
- Use your API key as the secret
- Use the raw JSON body as the message
- Important: If reconstructing from JSON object, ensure consistent serialization using
json.dumps()
withsort_keys=True
andseparators=(",", ":")
to match EximPe’s format - Generate HMAC-SHA256 hash
- Convert to hexadecimal string
Compare signatures
Compare signatures - they should match exactly
Code Examples
⏰ Retry Logic & Delivery
EximPe implements an automatic retry mechanism to ensure reliable webhook delivery. If your endpoint doesn’t respond with a 200 OK
status code, we’ll retry the webhook delivery according to the following schedule:
Retry Schedule: 1st attempt is immediate, followed by retries at 1 minute, 5 minutes, 15 minutes, and finally 1 hour. After 5 failed attempts, EximPe will stop retrying.
Security Best Practices:
- 🔐 Never expose your encryption key publicly
- 📝 Always verify webhook signatures
- 🛡️ Use HTTPS endpoints only
- 📊 Log webhook events for audit trails
Next Steps:
- Review the API Reference for detailed webhook payload specifications
- Test your webhook integration in the sandbox environment
- Monitor webhook delivery in your EximPe dashboard