📢 Overview
The Capa API provides a webhook-based notification system that allows third-party partners to receive real-time updates whenever specific events occur in our backend systems. This enables partners to stay informed about changes related to their users or transactions and to make necessary updates in their systems accordingly.🔧 How It Works
-
🔗 Registering a Webhook URL:
Each partner can register a single URL where they wish to receive webhook notifications. This URL must be provided through the designated endpoint. Set Webhook Settings -
📬 Receiving Notifications:
Once a URL is registered, partners will receive notifications whenever an event relevant to them occurs, such as:- 📝 Updates to a user’s KYC (Know Your Customer) status.
- 💸 Transaction status changes
-
📡 Notification Handling:
If a notification fails to be delivered (e.g., due to network issues or a problem on the partner’s end), the system will automatically retry the delivery up to 5 times with the following delays:If all attempts fail, the notification will be marked as “Failed.” There is currently no API endpoint or dashboard feature to replay missed webhook events. As a fallback, use the Get KYC Details or List Transactions endpoints to poll for the latest status.Attempt Delay 1st retry Immediate 2nd retry 1 minute 3rd retry 5 minutes 4th retry 10 minutes 5th retry 15 minutes -
🧪 Mock Testing:
Webhooks do fire during mock testing in the staging environment, as long as a webhook URL is configured. This allows you to test your webhook handling end-to-end using the Mock Testing Guide.
💡 Best Practices
- 🕒 Ensure Availability: Make sure your webhook URL is always available to receive notifications.
- 🤖 Handle Retries Gracefully: Implement logic to handle repeated notifications in case of retries.
- 🔍 Validate Data: Validate all incoming data to ensure it is from a trusted source and in the expected format.
- ✅ Respond with 2xx: Return a
200or2xxstatus code promptly to acknowledge receipt. A non-2xx response triggers retries.
What’s Next