Webhooks
Stay up to date with the latest events in your Okra apps with webhooks
Overview
Webhooks provide real-time notifications when important events take place in your Okra app. You can subscribe to these events by setting up a webhook URL and receive notifications to your system in simple JSON payloads.
Webhook responses correspond to the Okra products that you enable in your Okra app. Some examples when Okra sends webhook notifications:
- a user successfully connects their account
- a user's account needs reauthentication
- an identity profile is ready
Use these notifications for tasks that require a response via the API, such as asynchronous requests, retries, or any other operation that needs processing on the backend of your application.
How to use
Okra recommends that you follow this workflow to ensure a smooth flow of information in your app:
- Ensure that your app can receive webhooks
- Subscribe to webhooks to receive event notifications and up-to-date data
- Check that your integration follows the best practices
Receiving events
To receive event notifications from Okra, you simply need to open an unauthenticated POST route in your application. The Okra API sends event notifications as a JSON payload in the request body.
Sample code for receiving events in NodeJs and PHP:
Subscribe to webhooks
You can subscribe to webhook notifications in 3 ways:
In the App Builder
Add your preferred webhook URL to the callback_url field in the App Builder when building your Okra app. Okra uses this URL to deliver event notifications about all products as POST requests. Using this subscription method, you can define an app-level webhook URL.
You can define this URL in both the Quick link and the Full customization options in the App Builder. Check out the Customization guide for more details.
In the Dashboard
Set up your preferred webhook URL on the Webhooks page in the Dashboard. Okra uses this URL to deliver event notifications about all products as POST requests. Using this subscription method, you can define a project-level webhook URL.
- On the Configuration tab, select your preferred API environment.
- Add your URL that receives event notifications
- Add your secret API key as the bearer token and Save your changes.
When building with options
You can programmatically add your preferred webhook URL using the callback_url app property. Okra uses this URL to deliver event notifications about all products as POST requests. Using this subscription method, you can define an app-level webhook URL.
Visit the Embed your app guide to learn more about this integration option, and check out the available Okra app properties.
Webhook levels
Okra provides webhooks on 2 levels: app and project.
App-level means that Okra sends notifications to your preferred webhook URL only about a specific Okra app. This enables you to define different webhook URLs for different apps, giving you more flexibility when working with multiple app integrations.
- Set up app-level webhooks in the App Builder or when building with
options.
Project-level means that Okra sends notifications to your preferred webhook URL about every Okra app in your active project.
- Set up project-level webhooks in the Dashboard.
Webhook priority
The Okra API always tries sending webhooks to app-level webhook URLs first.
- If you do not define an app-level webhook URL, the API tries sending the webhooks again to the project-level URL.
- If you do not define a project-level webhook URL, the Okra API does not try sending the webhooks again.
Payment webhooks
These are the available Payments webhook events:
PAYMENT_SUCCESSPAYMENT_FAILEDPAYMENT_CANCELLED
When a payment fails, you can find the detailed reason for the failure in the PAYMENT_FAILED webhook payload's payment.error object.
This object contains the error code and the error message fields that help you determine the exact cause why a specific payment failed. payment.error.message can contain information directly provided by the bank.
Check out the Payment errors reference for more details.
Sample Payment webhook responses
You can check sample Payment webhook responses here.
Data webhooks
See this table for a list of available webhook events for Okra's Data products:
Sample Data webhook responses
You can check sample webhook responses for Okra's Data products here.
User authentication webhook
The USER_DISCONNECT webhook notifies you when a user disconnects their account.
Sample payload for this event:
{
"message": "Customer disconnected an account",
"event": "USER_DISCONNECT",
"data": {
"accounts": ["53456ef366890da2345"],
"customer": "534fd4575d3290da2445",
"my_okra": true,
"disconnect": true,
"disconnected_by": "134fd4575d3290da2222",
"disconnected_at": "2023-09-12T12:11:20.750Z"
}
}Best practices
Follow these best practices to ensure that your webhook implementation runs smoothly.
Monitoring webhooks
- During integration, Okra recommends that you test and monitor that your app can successfully receive event notifications. You can use services like Webhooks.site or Pipedream for testing and monitoring.
Setting up webhook URLs
- If you are using
.htaccess, make sure that you add the trailing/to the URL you set. - Test your webhook URL with a
POSTrequest to ensure that it is able to receive the request body. - Make sure that your webhook URL is publicly available.
localhostURLs cannot receive events.
Whitelisting webhook IPs
Okra delivers webhooks from these IP addresses:
13.39.179.18813.38.152.1835.180.165.18
Responding to event notifications
Okra recommends that you respond with a 200 OK status message when you receive an event notification. You do not need to provide a request body or any other parameters, only the status code. The Okra API considers this as a confirmation that your app has received the notification.
If your app returns any status other than 2xx, the API considers the notification as "not received". Based on Okra's retry policy, the API continues to send the notification every hour for the next 72 hours.
If your app starts a longer process in response to an event notifiction without sending a 200 OK status message, the Okra API might time out in waiting for a response. The API considers this timeout the same as a notification that is "not received" and falls back to the retry policy. Okra recommends that you avoid duplicte notifications by sending a 200 OK status message immediately when you receive an event notification.
Matching keys
All webhook requests are sent with an Okra-Auth header for verification. Okra recommends that you verify and match the webhook secret key you passed when creating this webhook.
Sample code on how to verify incoming webhook requests in Node JS
// Javascript Implementation
const secret = process.env.OKRA_WEBHOOK_KEY;
function verifyWebhook(req, res, next) {
//isVerified is a function that verifies the token
if (!isVerified(req.headers['Okra-Auth'])) {
return res.status(401).json({
message: "Unauthorized request."
});
}
next();
}
router.post('/create', verifyWebhook, (req, res) => {
const webhook = req.body;
switch(webhook.event) {
case "okra.event":
// do something with webhook.data.account;
break;
}
return res.sendStatus(200);
});Trigger webhooks
Okra enables you to trigger webhooks for specific user records, to any URL that you set up. Triggering webhooks can be useful in these scenarios:
- You want to trigger webhooks to an alternative webhook URL for certain users
- You want to check the status of a webhook
- Your app did not receive webhook events due to technical issues and you want to retrigger failed event notifications
You can trigger webhooks by sending a POST request to the /callback/trigger endpoint:
- Use your secret API key for bearer authentication
- Use these body parameters to specify your request:
Webhooks for async data processing
Some of Okra's products, like Balance and Transactions require asynchronous data processing.
For these products, the Okra API provides a URL instead of immediately returning a response. You can periodically ping this URL to see if data processing is ready or not.
{
"transactions":{
"callback_url":"https://api.okra.ng/v2/callback?record=14ad5be8d14dd70039585b0c&method=TRANSACTIONS"
}
}Example request:
curl -X GET https://api.okra.ng/v2/callback?record=14ad5be8d14dd70039585b0c&method=TRANSACTIONS"
-H 'Content-Type: application/json'
-H 'Authorization: Bearer {your_secret_API_key}'- Send a
GETrequest to the/callbackendpoint - Use the
recordandmethodvalues that you received in the webhook as query parameters - Use your secret API key for bearer authentication
Was this page helpful?