Let's take a short scenario exercise to get your creative juices to flow:

You've always wanted to open a small library in your hometown as a side project, where only members may borrow books. You've achieved your goal, and your library is now operational.

In your quest to make your library grow, you run into a problem, that is - You're a busy person, after all, and you're not able to be in the library 24 hours a day, seven days a week. So you hire someone to keep you informed about what's going on at the library on a regular basis. There are only two people that apply for the interview, and each of them is unique.

1. There's Mr. Bola Peters (aka API), a highly capable assistant who responds to your questions. So, if you call him and say, "Hey!" Did anyone subscribe today? You'll get the list of subscribers for that day.
2. Mrs. Bimbo Davids (aka Webhooks), on the other hand, adopts a different method. When a person joins the library, she automatically sends you a message even if you didn't ask for it saying, "Hey! Toke Martins has joined your Platinum plan. Here's some more information on her!”

Who will you hire? is the question.

Isn't the answer rather obvious? This guide is all about reiterating that response and demonstrating why you should not overlook webhooks when it comes to real-time notifications and data syncing in your apps.

What are webhooks?

In technical terms, a webhook is basically a user-defined HTTP callback that is triggered when a particular event occurs at the source site. When the event occurs, the source site makes an HTTP request to the URL specified as a webhook.

Imagine a doorbell system that has a button on the entrance and a bell in the living room. You hear the doorbell ring when a visitor presses the button, indicating that someone is at the door - implying that a signal is transferred from the button to the doorbell.

Webhooks are based on the same approach. When a defined event happens, the entrance door is a third-party app/site (webhook provider) that transmits a signal. In the software space, the bell in your living room is known as the "listener." The listener is a URL that receives webhooks and then executes a preset action.

You may even set up an event on one site to cause an action on another.

The basic difference between API calls and webhooks, as you've probably figured out by now, is that the former uses request-based output mechanisms, whilst the latter uses event-based output mechanisms.

Webhooks in action

Coming back to the library scenario, assume that only your paid subscribers will be able to access your publications, but that each subscriber will receive a free one-month trial. Let's assume you have five separate webhooks configured for five distinct events:

• subscription_created: Sent when a subscription is created
• subscription_trial_ending: Sent when a customer's trial period is about to end
• add_card: Sent when a customer's card is added
• payment_received: Sent when a payment is successfully collected
• subscription_activated: Sends when a trial subscription becomes active.

Let's have a look at how they function in the following scenarios:

Day 1: Y, a visitor, signs up for a free trial. The source site will make an HTTP POST request to a URL you specify with the subscriber's details, and your customer database will be instantly updated, thanks to the webhook specified for the "subscription_created" event.

24th Day: The free trial of Y will expire in one week. You'll be alerted about this if you use the webhook for "subscription_trial_ending." You may show a banner/alert on Y's profile with a little code and setup, telling Y that the trial period is coming to an end and giving Y a link to change the pricing plan and card details, which you'll use to charge Y at the end of the trial.

Y is now a huge fan of your service and refuses to stop using it. Y quickly inputs the card information. The “card added” webhook will be triggered, and the associated details in the customer database will be updated.

32nd Day: When the trial period is up, you charge the card, and the transaction is complete! It's time for the "payment_received" webhook to be triggered, which will convert the subscription's status from trial to active. The “subscription activated” webhook is triggered, and an email is sent to notify Y that the payment was successful. Your client database will also be updated as a result of this.

So, if you automate the process with the aid of webhooks and add some code snippets as we will get into later in this article, all of this will continue to happen with little or no interaction from you.

Using Webhooks with Okra

We trigger events that your application can listen to whenever certain actions occur through your Okra integration. Here's where webhooks come in handy. We deliver payloads for such events to a webhook URL on your server. If you use webhooks, for example, we'll send a balance. success event to your server as soon as a balance is retrieved. This is a list of events we can send to your webhook URL.

You can specify your webhook URL on your dashboard where we would send POST requests whenever an event occurs.

Here are some things to note when setting up a webhook URL:

1. If using .htaccess, remember to add the trailing / to the URL you set.
2. Do a test post to your URL and ensure the script gets the post body.
3. Ensure your webhook URL is publicly available (localhost URLs cannot receive even).

Prerequisites

• Create a developer account
• Create an app and retrieve your client_token and secret_key

Set up Webhooks

Event notifications are managed by creating a "webhook endpoint" and specifying which events you would like pushed to that endpoint.

1. Set up an endpoint on your server to listen for notifications
2. Create a POST route on your application, specifying the endpoint URL and which events you would like to get notifications for.

The event object is sent as JSON in the request body.

Webhook Example Implementation

Responding to an event

A 200 OK should be used to respond to an event. This is considered an acknowledgment by your application. If your application returns a status other than 200, we will consider it unacknowledged and we will retry every minute for the first 3 minutes then we retry every 15 minutes for the next one hour. We backoff if we don't get a 200 response from the server in an hour. You don't need to provide a request body or any other parameters because they will be ignored - we only care about the status code.

If your webhook script is performing a complex task, it's likely that the HTTP connection times out before the tasks are completed and Okra would not receive the 200 HTTP status response from your server. It's recommended that you immediately acknowledge receipt with a 200 HTTP status code before running the complex task

Example Incoming Webhook

If you're using callbacks with any product, you'll receive a callback when Okra finishes processing the product's data for the Record. Once you receive this callback, you can make an API call to retrieve the product's data.

Below you will see an example of an incoming webhook from Okra's servers. The below example is for AUTH but you will receive webhooks for all products.

Checking a Webhook status

Product Callbacks/Webhooks

The following are the current events that we have for you. As we hook into more actions in the future, we'll add to this list.

Webhook Trigger

The webhook trigger can come in very handy if you need to get the webhooks associated with a particular record id(s), in scenarios where the server goes down unexpectedly or you want to send webhooks to a different server.

You can use the webhook trigger to check the status of a webhook by supplying their record id(s) as the payload to the webhook trigger endpoint.

The way these works is by, calling this endpoint https://api.okra.ng/v2/callback/trigger, and passing the array of recordIds, you can also pass in the URL you'd like to redirects the webhooks to.

Note that the records array accepts a maximum of 100 record ids

To summarize, webhooks may be used to:

• To confirm that an event has occurred
• To adapt/customize apps and their features to meet specific requirements
• To link two or more apps together such that an event in one app triggers an event in another.

Conclusion:

Webhooks, in a nutshell, delivers immediate, real-time notifications.

An API requires you to poll for new data at regular intervals, but webhooks delivers pre-requested data to other apps when an event happens.

The underlying benefit of webhooks is greater efficiency, or in other words, fewer headaches.

To get started, signup here and start building today!

A good place to check other cool stuff is our docs, and if you are passionate about open finance, you definitely should visit our website, to see other services that might be appealing to you.

Contact sales or send an email to sales@okra.ng to get started!