Introduction to webhook

What are webhooks

Webhooks are an important aspect of your integrations, they notify you about events that occur regarding the API actions you take i.e. payments that you process with the Atlas API, like status changes on payments. You can select which type of events you want to be notified about and where we should send them to. This allows you to be easily aware of things that happen and take action when necessary, even after the consumer is no longer on your site.

Where to use Webhooks

Webhooks are notifications sent by the Raven Atlas Platform only when needed, so basically we don't send notifications for all API actions you take, i.e. when you retrieve your customer's collection. There are two ways Atlas webhook events get triggered.

• Because of an API call you made.

• As a response to Requests that were processed asynchronously. For example, for many local payment methods such as bank-to-bank transfers, the outcome of such payment request might not arrive immediately and might take several hours to confirm. What Raven Webhook does is to keep check of such transaction status, and when it receives an actionable response, it sends it to you as a webhook notification.

Events of the first type might not add value for you since you'll get informed about them via the API call's response, anyway.

However, events of the second type are more interesting to subscribe to using webhooks. Let's look at an example:

• A payment reverse for bill payment, the customer initially got notified that the bill payment was successful, however, because of irregularity from the Third Party Service Provider, the payment was reversed, without webhook, such payment will remain as successful on the client side which might result to customer issues, but with webhook, you can take actions regarding the transaction, i.e. credit the merchant wallet for the reversal.

• The online authorization of a redirect payment only happens after the consumer finishes the process at the 3rd party provider. This action is not visible to you as the consumer is not on your website at that time. You could periodically check the current payment status using our API ('poll'), but that is not very efficient. Instead of APAI Calls we use webhooks, you can subscribe to one or more API events, which will trigger us to do a POST request to an HTTPS endpoint on your server at the moment the payment status changes. Or in webhooks terms: when the event occurs.

This is just an excerpt of what you can use webhooks for, your use cases totally depend on your business needs.

Processing Webhooks

To start accepting and processing webhooks requests you need to do a few things first,

1. Identify the events you want to monitor and the event payloads to parse.
2. Create a webhook endpoint as an HTTP endpoint (URL) on your local server.
3. Handle requests from Atlas by parsing each event object and returning 2xx response status codes.
4. Test that your webhook endpoint is working properly using the Test payload data provided on this documentation page
5. Deploy your webhook endpoint so it’s a publicly accessible HTTPS URL.
6. Register your publicly accessible HTTPS URL in the Raven Atlas dashboard.

Step 1

Raven Atlas currently sends webhook notifications for 5 Transaction Types which are namely;

1. Transfer
2. Transfer Reverse
3. Electricity bill payment
4. Electricity Reverse

Step 2

API Notifications are sent as HTTPS Callbacks(Webhooks) Raven Atlas requires you to accept these callbacks through an HTTPS endpoint using TLSv1.2, with emphasis on the 'S' in the HTTP.

To Recieve our HTTP Callback

• An endpoint that can receive a JSON call, or an HTTP POST.
• For test environments: an open TCP port for HTTP traffic (80, 8080, or 8888) or HTTPS traffic (443, 8443, or 8843) with TLSv1.2.
• For live environments: an open TCP port for HTTPS traffic (443, 8443, or 8843) with TLSv1.2.

👍

Security & Firewall

Depending on your security configurations, to ensure you receive our webhook notification always, you might need to add our domain and IP to your allow list, to retrieve our IP address you can reverse lookup our domain integrations.getravenbank.com , it's advisable you do a periodic check as our IP is subject to change, or you can hardcode it to periodically retrieve our current IP address.

Step 3

It is important we receive an OK(200 Status) response from you, this is the only way we know you received our notification so we stop retrying in case of failed POSTs

Step 4

For now, we currently don't offer any webhook testing SDKs, however, you can simulate a webhook post on your end using our test payloads available on the next page

Step 5

Just as any other publicly accessible webpages, we need your webhook URL to do the same, this will allow us to send a post request with ease to your server without fail, however, in case of security configurations you can always whitelist our IP and Domain by adding them to your allow list.

Finally

You need to register your newly configured Webhook URL on your Raven Atlas Dashboard, you can do so by accessing Atlas > Settings > Webhook URL & Secrets.

This is all you need to do and know about the Raven Atlas Webhooks.