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:Merchant Approved
When: A sub-merchant is approved
Use Case: Enable the merchant to hold VBAs and collect
Use Case: Enable the merchant to hold VBAs and collect
Payment Successful
When: A credit lands in a VBA and a payment is created
Use Case: Begin LRS verification for the credit
Use Case: Begin LRS verification for the credit
Payment Failed
When: A credit could not be processed
Use Case: Investigate and reconcile
Use Case: Investigate and reconcile
Payment Settled
When: Funds are settled to the beneficiary
Use Case: Update accounting and reconciliation records
Use Case: Update accounting and reconciliation records
Payment Refunded
When: A refund is processed
Use Case: Update your ledger, notify the buyer
Use Case: Update your ledger, notify the buyer
Refund / Dispute Updates
When: A refund status changes or a dispute is updated
Use Case: Track refund and dispute lifecycles
Use Case: Track refund and dispute lifecycles
🛠️ 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
1
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)
2
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
1
Extract the signature
Extract the signature from the X-Webhook-Signature header in the request
2
Get your Encryption Key
Get your Encryption key

3
Recreate the signature
Recreate the signature using HMAC-SHA256:
- Use your Encryption 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=Trueandseparators=(",", ":")to match EximPe’s format - Generate HMAC-SHA256 hash
- Convert to hexadecimal string
4
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 a200 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.
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