Webhooks Overview

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.

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, and PATCH.
• Send data using structured JSON or XML 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.