Learn how to use webhooks to receive Mambu Payments events in your application
1. Introduction to webhooks
Mambu Payments uses webhooks to notify your application when an event is created. Webhooks are particularly helpful for asynchronous events, such as a payment being executed by the bank or an account statement being received from a bank.
Events are created when an object is created or updated, either by a user using the API or the dashboard or by Mambu Payments. An update can be the update of any attribute, such as a status, a date, or any other data.
For each event, Mambu Payments will send a POST request to your API endpoint in JSON format. This API request contains an event object.
2. Registering a webhook
In order to use webhooks, you should create an API endpoint on your server and register it using the Mambu Payments dashboard. Learn how to add a webhook.
3. Event delivery modes
Events support multiple delivery modes.
| Delivery mode | Default delivery mode | Order guaranteed | Throughput |
|---|---|---|---|
| Individual events | ✅ | Yes | Base |
| Batched events | - | Yes | High |
| Parallel individual events | - | No | High |
| Parallel batched events | - | No | Highest |
The order is defined as the order of events for a given object, based on its lifecycle.
To guarantee order, Mambu Payments waits for the acknowledgment of receipt of an event before sending the next event. This means, for instance, that a payment_order.processing event will always be sent before a payment_order.sent event, as per the payment order lifecycle.
There are some edge cases where the order of the messages delivery is not deterministic (or might not be as you expect). For example, if you create a payment order via a sync HTTP API call, you may receive a notification that the payment order is pending_approval even before you get a response for the sync HTTP API call to create the payment order.
When events are sent in parallel, Mambu Payments does not wait for the acknowledgment of receipt of an event before sending the next event. As a result, order is not guaranteed. As an example, payment_order.sent might be delivered before payment_order.processing event.
The maximum number of events in a batch is currently set to 100 for deliverability and performance reasons. Higher limits can be discussed on a case-by-case basis.
Contact us at [email protected] if you would like to receive events other than as individual events.
4. Webhook idempotency
Mambu Payments guarantees that every event is sent at least once. In rare cases, an event can be delivered more than once to the same webhook, even after a previous delivery already succeeded.
To handle this, every webhook payload includes an idempotency_key attribute in its JSON body. When an event is sent individually, the TX-Webhook-ID HTTP header also carries this value.
The idempotency key is unique for each event / webhook combination. If an event is redelivered, it always carries the same key.
Because redelivery can happen, your integration must implement deduplication using the idempotency key. Store the keys you have already processed and discard any incoming event that repeats one.
5. Verifying webhooks
Webhooks sent by Mambu Payments always originate from the same IPs. They can also be signed and authenticated with an API key or using OAuth2.0. Learn more in the dedicated guide.
6. Acknowledgment of receipt
To acknowledge the receipt of an event, your API endpoint must respond with a 2xx HTTP status code to Mambu Payments within 5 seconds.
7. Exponential back-off strategy
If your API endpoint takes longer to respond or returns an HTTP status code different from 2xx, the event will be set to pending_retry status and re-sent using an exponential back-off strategy. The delay between retries doubles each time, starting at 10 seconds.
When a webhook delivery attempt fails (due to a network timeout, connection error, or non-2xx HTTP status code), Mambu Payments automatically retries delivery using an exponential backoff strategy. By default, failed events are retried over a total window of approximately 80 seconds before the channel is marked as blocked:
| Attempt | Delay from first attempt |
|---|---|
| Initial delivery (attempt 1) | 0 seconds |
| Retry 1 (attempt 2) | 10 seconds |
| Retry 2 (attempt 3) | 20 seconds |
| Retry 3 (attempt 4) | 40 seconds |
| Retry 4 (attempt 5) | 80 seconds |
If your endpoint requires a longer recovery window (e.g., 6 total attempts spanning ~5.5 minutes), it can be adjusted for your webhook channel configuration upon request. Contact support or your account manager to increase the attempt threshold.
After all retries are exhausted, the event is set to failed.
A new optional maximum wait time parameter can be configured per webhook. It sets an upper bound on the cumulated time an event will be retried from its first delivery attempt. When this duration is exceeded, the event is marked as failed regardless of the number of remaining retries. This is useful when timely delivery matters more than maximizing retry attempts. If not set, the existing behavior (retry until the number of retries is exhausted) is preserved.
If the event delivery mode is sequential or batched, Mambu Payments will block the webhook and stop sending events in order to guarantee their order.
We recommended adding a notification email address when configuring your webhook to be notified in case a webhook is blocked and events are no longer sent.
8. Retry events in case of webhook failure
To retry events after you have fixed your webhook, use the Retry failed events API endpoint or dashboard feature (Developers > Events > Retry failed events).
9. Re-send an event already delivered
To re-send an event previously successfully delivered to the same or another webhook, use the Resend event API endpoint. This can serve different operational purposes like data analysis or reporting.