​
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:
https://www.example.com?EventType=EventType&RessourceId=Id&Date=Date
Mangopay webhooks rely on the Hook object of the API. The available EventType values are listed in the event types list. 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).
1

Define the URL to which you wish to receive the notification

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 from which Mangopay sends hook notifications.
Note – Use a TLS 1.2 certificateYour 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.
2

Create the Hook for the event type

If using the Dashboard, navigate to Developers > Webhooks > Add webhook, then select the event type and enter your URL.You can also specify and optional Tag.If using the API, call the POST Create a Hook endpoint, specifying your Url.In response, the API returns the Hook object and its HookId.
API response example
{
    "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
}
3

Create or act on the resource that leads to the event

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.
4

Listen for the notification on your URL

An example of the notification for the Hook in this example would be:
https://www.example.com?⁠EventType=USER_ACCOUNT_ACTIVATED&RessourceId=user_m_01JQVHDG0S0TJP5KFX029211BF&Date=1743627006
The RessourceId is the Id of the user that completed the SCA session.
5

Trigger a GET call on the relevant resource

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), 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 and the full lists 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 full listThe 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 10 consecutive failed notifications (new or retries) for the same EventType, you receive an email warning you of the issue. After every 10 additional failed notifications you receive another email until the 100th consecutive failed notification. When the counter of consecutive failures reaches 100, the Hook object’s Validity is set to INVALID and no more notifications are sent (new or retries). 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. 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 endpoint:
API request
{
    "Validity": "VALID"
}
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:
API request
{
    "Status": "DISABLED" // "ENABLED"
}

​
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:

Guide

See the list of available event types

Endpoints

The Hook object