What is a Webhook?
Webhooks can be simply described as a means through which applications communicate with each other automatically. When a specific event occurs, a webhook can be fired instantly to send real-time data from a software program to other web services automatically.
To effectively receive real-time webhook updates, there would be a need for an entry point or channel to have these webhook events delivered. This entry point can be defined as a webhook URL. It is through this URL endpoint that data (event payloads) gets fired based on different activity triggers.
Webhooks are, in some cases, called “reverse APIs,” since communication is initiated by the application sending the information instead of the one accepting it.
Unlike traditional APIs, with webhooks you don't have to poll for data very often to receive real-time results, you automatically get notified when a particular event occurs.
How do webhooks work?
Here’s a simple analogy to help you understand how webhooks work.
Let’s assume you run a fitness gym and you require new customers to sign up and pay for a membership plan using your fitness app. If a webhook is set up, every time a customer pays for a membership plan through a payment gateway (the trigger application), the payment gateway will send this event through a webhook URL to alert you of the payment and its status, whether successful or failed. If the payment was successful, the fitness app can automatically add the user as a member, match them with a fitness trainer, and allow access to the app features.
Now, how can you set up webhooks for your app and how can they be used to receive different webhook events? To show how this works, we will explain the types of webhooks used on Mono and how you can set up webhooks on Mono.
How webhooks improve your integration and experience on Mono
When you integrate any of Mono products to your app, — Mono Connect, Mono DirectPay, or Mono Lookup — we send various kinds of webhooks directly to your webhook URL immediately after a specific event takes place. This allows you to take the required action on your app, based on the nature of the event and data received.
Once you’ve successfully integrated Mono APIs and set up a webhook URL, you can receive different webhook events on your web service, but for the purpose of this article, we will focus on the following three webhook events and when they are sent:
Account Connected event
Account Updated event
Payment Successful event
1. Account Connected event
This webhook event (mono.events.account_connected) is sent when a user successfully connects their financial account using the Mono widget.
Once this event is received, you can notify the user that their account has been connected successfully. The webhook payload for this event looks like this:
2. Account Updated event
After a user securely links their financial account to your service, you may need to see more recent transaction data from transactions made after they linked their account. If it is set up, this webhook event (mono.events.account_updated) will be sent once new financial data is available on the connected account. It will include the user’s account details and the newly updated account balance to show that recent transaction data has been returned from the user’s account. The payload for this event should look like this:
3. Payment Successful event
When a customer initiates and successfully completes a direct bank payment, to any business that accepts direct bank payments using the Mono Directpay product, this webhook event (direct_debit.payment_successful) is sent. When this is received, it allows you to send your user a notification that their payment is received and proceed to provide value. The payload contained in this event is:
Best practices for setting up webhooks
When setting up webhooks on Mono, there are a few things you should consider to ensure seamless integration with Mono’s services. They include:
1. Response speed: Your webhook URL endpoint should respond to webhooks as quickly as possible. To acknowledge receipt of a webhook, your endpoint must return a 2xx HTTP status code. This status code should only indicate receipt of the message, not an acknowledgement that it was successfully processed by your system, you don’t need to take note of any other information that is returned in the response headers or response body.
2. Correctly matched keys: All webhook requests are sent with a mono-webhook-secret header for verification. It is recommended that you verify and match the webhook secret key you passed when creating this webhook.
Please note that for each webhook URL added to your app on the Mono dashboard, a webhook secret key is automatically generated for easy verification.
Here’s an example of how to verify incoming webhook requests via the webhook secret key in Node JS:
How to set up webhooks on Mono
Before you can receive any of these webhook events on your servers, you need to set up a webhook on Mono. As we mentioned, when a particular event happens, a webhook is how this (event) data can be exchanged between two applications, through a webhook URL. Also, this means that Mono will be the application that sends this data and your app will receive this data.
Here’s how you can set up a webhook on Mono in four simple steps:
1. First, log into your Mono dashboard and navigate to the Apps page.
2. Next, click on an already created app.
3. Then, under the Webhooks section, click the Add webhook button and fill in the URL from your server's backend with a service to handle all webhook URLs.
4. Once done, your app gets updated with your webhook URL alongside a webhook secret key for further authentication in your headers.
Webhooks are a simple method for sharing information in real-time between two different application systems.
In this short article, we have explained what a webhook is and how to set up webhooks on Mono. To learn more about the types of webhooks you can set up on Mono, you can go through our API documentation.
