> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mangopay.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Webhook notifications
## Format
Mangopay provides a webhook feature to submit notifications to other applications whenever a specific event occurs for a specific API object.
The notification is a GET HTTP call with query parameters in the format:
Mangopay webhooks rely on the [Hook](/api-reference/webhooks/hook-object) object of the API. The available `EventType` values are listed in the [event types list](/webhooks/event-types).
The value of the (misspelled) `RessourceId` parameter is the unique identifier of the corresponding API object on which the event occurred. For example, for the `EventType` value `PAYIN_NORMAL_SUCCEEDED`, the `RessourceId` value is the `Id` of the specific pay-in (the `PayInId`).
The `Date` value the a Unix timestamp (UTC) of the date and time the event took place.
## How it works
To set up a webhook, you can use the API or the Mangopay Dashboard (***Developers*** > ***Webhooks***).
Your page must respond with a HTTP 200 response within 2 seconds for Mangopay to consider the notification valid.
Ensure you allow the [IP addresses listed below](#ip-addresses) from which Mangopay sends hook notifications.
**Note – Use a TLS 1.2+ certificate**
Your endpoint must be protected using a TLS 1.2+ certificate. Endpoints using self-signed certificates, SSL certificates or TLS versions 1.0 and 1.1 may be rejected by our webhook systems.
**Best practice – Ensure your URL complies with these best practices**
To ensure a health connection, please verify that your URL is:
* Accessible and responding with a 2XX HTTP status code
* Not blocked by any firewall for incoming requests from Mangopay’s [IP addresses](#ip-addreses)
* Using a valid SSL certificate (for HTTPS)
* Able to handle the expected request volume
If using the Dashboard, navigate to ***Developers*** > ***Webhooks*** > ***Add webhook***, then select the event type and enter your URL.
You can also specify an optional `Tag`.
If using the API, call the [POST Create a Hook](/api-reference/webhooks/create-hook) endpoint, specifying your `Url`.
If integrating after April 2026, set an `Email` address for consecutive failed notification alerts – [read more](#email-alerts-for-consecutive-failed-notifications).
In response, the API returns the Hook object and its `HookId`.
```json API response example theme={null}
{
"Url": "https://webhook.site/e1def644-2cee-4669-a4a6-b6ceeacc621b",
"Status": "ENABLED",
"Validity": "VALID",
"EventType": "USER_ACCOUNT_ACTIVATED",
"Id": "hook_m_01JQW43GW82MJ23HB8Y6B3JZ72",
"Tag": "Created using the Mangopay Postman collection",
"CreationDate": 1743626814,
"Email": "tech@example.com"
}
```
A webhook notification is sent when the event type occurs for a specific API resource – when it is created or changes status.
In the example above, for `USER_ACCOUNT_ACTIVATED`, the resource is a Natural or Legal User with the `OWNER` `UserCategory` that was created or categorized with the SCA-enabled endpoints.
When SCA was triggered by a call to one of these endpoints, the `UserStatus` was set to `PENDING_USER_ACTION`. When the user completes the SCA session, their `UserStatus` changes to `ACTIVE`, triggering the `USER_ACCOUNT_ACTIVATED` event and the webhook notification.
An example of the notification for the Hook in this example would be:
The `RessourceId` is the `Id` of the user that completed the SCA session.
When your system receives the hook notification, you should trigger a GET call on the relevant API object, as listed in the event types list, using the `RessourceId` of the notification.
This allows you to check that the event is still relevant and ensure that the notification is authentic.
Continuing the example above, you would trigger a call to [GET View a User (SCA)](/api-reference/users/view-user-sca), using the value `user_m_01JQVHDG0S0TJP5KFX029211BF` as the `UserId` path parameter.
In the API response, the `UserStatus` shows as `ACTIVE`, confirming that the event is still valid. The User object also returns other relevant information needed for your integration, such as name, email (for example, to send confirmation), and other key data.
## IP addresses
Mangopay sends webhook notifications from the IP addresses listed below in both the Production and Sandbox environments. Depending on your firewall or network security setup, you may need to add them to an allowlist to receive notifications.
The CIDR ranges given below express the same IP addresses. The `/32` indicates that only there is only one IP address in the range.
**Note – Contact Mangopay for addresses**
The IPs below are redacted for security reasons. When your platform is looking to test webhooks in Sandbox, contact Mangopay via the Dashboard for the full list.
**CIDR ranges:**
* X.XX.XXX.180/32
* X.XX.XXX.181/32
* X.XX.XXX.182/32
**IP addresses:**
* X.XX.XXX.180
* X.XX.XXX.181
* X.XX.XXX.182
## Notification retries and failure
If a notification for a specific `EventType` URL does not respond with 200 status code within 2 seconds, then the notification is considered as failed.
Mangopay retires the same notification:
* Every 10 minutes for the first hour
* Every 8 hours once the first hour is passed, and for the next 3 days
After 100 consecutive failed notifications for the same `EventType`, whether new ones or retries, the Hook object’s `Validity` is set to `INVALID` and no more notifications (new or retries) are sent for that Hook. Mangopay sends an email to notify you that the webhook is no longer emitting notifications – provided the email is configured ([see below](#email-alerts)).
The counter is reset as soon as there is 1 successful notification (new or retry) for the `EventType`. So if there are 99 failed notifications and then 1 successful one, the Hook is not set to `INVALID` and any retries continue.
Changing the `Url` does not reset the counter.
### Email alerts for consecutive failed notifications
When a Hook object reaches consecutive numbers of failed notifications for an `EventType`, Mangopay sends an email to notify your platform.
Emails are sent at:
* 25, 50, and 75 consecutive failed attempts, to warn you that Mangopay is not receiving a 200 HTTP response from your endpoint
* 100 consecutive failed attempts, to notify you that, as a result, the Hook's `VALIDITY` has become `INVALID` and notification attempts have stopped
In this case, you need to verify your URL and [reset the hook](#reset-a-hook) to re-enable notifications.
#### Configure an email for a webhook
If your platform is integrating after April 2, 2026, you must proactively set an email address for each Hook to receive alerts for consecutive failed notifications.
To do so, use the use the `Email` property on [POST Create a Hook](/api-reference/webhooks/create-hook) or [PUT Update a Hook](/api-reference/webhooks/update-hook).
**Caution - No alerts sent if email is `null`**
If the `Email` is not defined on a Hook and is `null` in the API response, the Hook still becomes `INVALID` after 100 consecutive failed notifications but email alerts are not sent.
This applies to all platforms, regardless of the change described below.
#### Transition from default email (April 2026)
Previously, Mangopay used a single global email address for all webhook notification alerts, rather than an email address per Hook object.
On April 2, 2026, Mangopay added the existing global email address and added it to all existing `VALID` Hooks in Production (as described below).
In Sandbox, no default email was set: the `Email` property must be set on creation or update to receive alerts.
##### Platforms integrated before April 2026
If your platform had valid Hooks in Production before April 2, 2026:
* The previous global email was added to all existing `VALID` Hooks in Production: the `Email` property shows the address used.
* Newly created Hook objects continue to automatically set the global email address by default, **unless and until** you create a Hook with the `Email` property set.
* As soon as you create a Hook with the `Email` property set or modify an existing one, other **new** Hooks created without the `Email` **do not** automatically use the global address for alerts (`Email` is `null` in response).
* If there was no global email set, then Hooks created before April 2, 2026 have `null` in the `Email` property.
This behavior means that your existing alerts are maintained and that there is no impact on new Hooks unless you set the `Email` proactively on a Hook. Mangopay will continue to set the email automatically, but recommends that you integrate the `Email` property.
##### Platforms integrated after April 2026
If your platform had no `VALID` Hooks in Production before April 2, 2026:
* No default email was set on any existing Hooks (`Email` is `null` in response)
* No alerts are sent in case of consecutive failed notifications and you won't be notified if a Hook becomes `INVALID`
You therefore need to:
* Update any existing Hooks to add the `Email` address using [PUT Update a Hook](/api-reference/webhooks/update-hook)
* Set the `Email` on all new Hooks created using [POST Create a Hook](/api-reference/webhooks/create-hook)
You can do this via the API directly (for example, using Postman): you can't yet manage the email via the Dashboard.
## Reset a hook
If a Hook is set to `INVALID`, you need to reset the Hook to `VALID` for it to receive future notifications.
You can do this via the Dashboard (***Developers*** > ***Webhooks***) or by using the [PUT Update a Hook](/api-reference/webhooks/update-hook) endpoint:
```json API request theme={null}
{
"Validity": "VALID"
}
```
**Best practice – Ensure your URL complies with these best practices**
To ensure a health connection, please verify that your URL is:
* Accessible and responding with a 2XX HTTP status code
* Not blocked by any firewall for incoming requests from Mangopay’s [IP addresses](#ip-addreses)
* Using a valid SSL certificate (for HTTPS)
* Able to handle the expected request volume
## Disable a hook
You can disable and re-enable a Hook to temporarily stop it receive notifications. You can do this via the Dashboard or by sending the relevant `Status` value on the PUT Update a Hook endpoint:
```json API request theme={null}
{
"Status": "DISABLED" // "ENABLED"
}
```
## Retrieving events
Mangopay provides an endpoint that retrieves all events triggered by your platform, regardless of whether you have subscribed to the `EventType` via a Hook.
The [GET List all Events](/api-reference/events/list-events) endpoint returns the events triggered up to 45 days ago, and you can target a specific time range using the `BeforeDate` and `AfterDate` query parameters.
Retrieving events can be useful if for any reason you suspect that a webhook might not have been received or realize that your Hook has become `INVALID` following 100 retries.
## Testing webhooks
In the Dashboard, you can send a test notification to check your URL is valid.
You can also use tools such as the following to obtain a URL for manual testing:
* [https://webhook.site/](https://webhook.site/) provides a temporary URL
* [https://webhook-test.com/](https://webhook-test.com/) provides a permanent URL if you sign up
* [https://pipedream.com/requestbin](https://pipedream.com/requestbin) provides a permanent URL if you sign up
See the list of available event types
The Hook object