Webhook Integration Guide#
Overview#
Our system provides real-time notifications about various events through webhooks. When specific events occur in our system, we'll send HTTP POST requests to your configured webhook URL with encrypted event data.Webhook Setup#
2.
Configure your webhook URL in the appropriate section
Security#
All webhook payloads are encrypted using the same encryption method as the API requests:AES-CBC encryption with standard padding
HMAC signature verification
Your merchant secret key is used for encryption
Webhook Payload Structure#
Each webhook request will contain:{
"encrypted_payload": "base64-encoded-encrypted-data",
"type": "EVENT_TYPE",
"hmac": "hmac-signature"
}
Event Types#
Our system supports the following webhook event types:1.
User creation results and KYC approval status
2.
Results of card application operations
3.
Results of card activation operations
4.
Results of physical card assignment to users
5.
Notifications when card status changes (LOCKED/ACTIVE)
6.
Results of card recharge operations
7.
Results of card closure operations
8.
Notification about new transactions
9.
Card correction and adjustment notifications
10.
3DS authentication requests requiring user action
11.
Card verification requests (e.g., Google Pay OTP)
Processing Webhooks#
1. Verify the Request#
Verify the HMAC signature using your secret key
Decrypt the payload using your secret key
2. Acknowledge the Webhook#
Return a 200 HTTP status code to acknowledge receipt
Respond within 10 seconds to prevent timeouts
Process the webhook asynchronously if needed
Example Webhook Processing (Python)#
Webhook Monitoring#
All webhook deliveries are recorded and can be monitored in the Admin Console:Callback Records#
Access the "Callback Records" section in the Admin Console
View the history of all webhook deliveries
Check delivery status and payload details
Troubleshoot failed webhook deliveries
Recommendations#
1.
Handle Failures GracefullyImplement proper error handling
Log failed webhook processing for debugging
2.
Keep your webhook URL secure (HTTPS)
Validate HMAC signatures for all webhooks
Store your secret key securely
3.
Regularly check the Callback Records in Admin Console
Set up alerts for failed webhook deliveries
Monitor your webhook processing endpoint's performance
Troubleshooting#
Common Issues#
1.
Verify you're using the correct secret key
Check if the payload is being modified in transit
2.
Ensure correct handling of IV and ciphertext
Verify the encryption key is correct
3.
Implement asynchronous processing for long-running operations
Return 200 OK quickly and process in background
Support#
If you encounter any issues with webhook delivery or processing, please:1.
Check the Callback Records in Admin Console
3.
Contact our technical support with relevant transaction IDs
Modified at 2025-12-09 12:30:51
