- 10 Jan 2023
- 2 Minutes To Read
- Print
- DarkLight
- PDF
Webhooks Overview
- Updated On 10 Jan 2023
- 2 Minutes To Read
- Print
- DarkLight
- PDF
Webhooks are a system to system communication tool that use a push-based communication strategy to allow you to set up user-defined HTTP callbacks for events happening in the Mambu application.
For example, you may set up a webhook to notify one of your applications that a loan has been disbursed. Mambu will make a POST
request to your application with a payload including information such as the loan account ID, client information, and amount. Your application can respond to this request itself or call back to Mambu to request more information and trigger additional actions in Mambu (such as creating a task or sending an email) or enrich and pass the call along to another partner service to trigger actions there.
For more information on setting up webhooks, see Defining a New Webhook.
The Streaming API is another system to system communication tool however it uses a pull-based communication strategy and therefore its infrastructure is more suitable for use cases where multiple client applications must consume a large amount of data from the Mambu application. For more information, see Streaming API in our User Guide and Streaming API in our API Reference.
Benefits of using Webhooks
Audit
The communication history records every notification sent out. The notification is stored with the version of the payload computed at send-out so, in case of failure, the originally computed version of the payload can be resent.
Assured Delivery
The engine backs up the delivery of the notifications with a retry mechanism built on the exponential back-off pattern. In case of an undelivered notification, the system will attempt to perform the call five times at progressively increasing time intervals. If this threshold is reached with no success in the delivery, no automatic retry is performed. A manual, on-demand retry option via the Notifications API can be used for resending individual failed communications and is also available for bulk re-send.
Flexibility
Mambu's Webhooks are highly configurable, they allow you to:
- Use an intuitive URL template for the call destination
- Create payload templates which can transport static and dynamic information (through the use of placeholders) in any format to the destination. For more information, see Placeholders.
- Support for REST API operations:
POST
,PUT
, andPATCH
. - Send data using structured
JSON
orXML
content types, or simply as plain text - Set up custom request headers
Idempotency
Given that webhooks are asynchronous and are transmitted across the internet, there is always a chance that the successful posting of a webhook from the Mambu Payment Gateway into the receiving system could fail, for example due to network timeouts.
Every Mambu webhook request includes an x-notifications-idempotency-key
header value. We highly recommend that you use this header value and design your systems receiving webhooks to act on events idempotently so that they bypass processing if it is a repeated value.
Security
We highly recommend using HTTPS(TLS v1.2) for all communications.
Authenticated calls are supported as long as the receiver's end is geared up with an authentication layer based on the Basic Authentication strategy: username and password.
Webhooks will originate from a fixed set of IP addresses per Mambu region. For more information, see Sender IP addresses.