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.

Troubleshoot webhooks

Webhook notification failure diagnosis

If your webhooks are failing, you can follow these steps to try and identify the issue:

1. In the Mambu UI, open the Communications tab.
   
2. For a more detailed view, follow these steps:
   1. Click on Edit Columns.
   2. Check the Include timestamps checkbox.
   3. Add the following columns to the list of viewed attributes:
      1. Creation Timestamp
      2. Failure Reason
      3. Failure Details
         
3. Find the correct notification.
   Once the Communication tab is configured with all necessary details, locating the failed webhook notification can be done by filtering and navigating through the records. To view the notification details:
   1. Find the failed notification entry.
   2. Click on it to open the full content.
   3. Review the details, including payload and response status.
      
4. Apply custom filters for large datasets.
   If there are too many notifications listed and the one of interest is not immediately visible, you can apply custom filters to narrow down the search.
   1. To apply a filter, click on the filter icon in the Communications tab.
      
   2. Create a filter based on specific criteria (e.g., status = failed, timestamp range, notification type).
      
   3. Preferably, use small time ranges to avoid SQL full table scans, which can impact performance. Move through results in small time chunks until you locate the notification.

Understanding failure reasons

The Failure Details column contains the exact reason why a webhook notification failed. Common failure reasons include:

• Destination unreachable (404 Not Found): The webhook URL is incorrect or the endpoint is down.
• Unauthorized (401 Unauthorized): The API key or authentication method is incorrect.
• Timeout issues: The destination server took too long to respond.
• Payload size exceeded: The message payload is too large for the receiver.
• Blacklisted URL: Mambu prevents sending webhooks to certain restricted addresses.

By reviewing the Failure Details column, the customer can immediately identify and resolve the issue without raising a Salesforce case.