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:
https://www.example.com?EventType= |
Mangopay webhooks rely on the Hook object of the API. The available EventType values are listed in the event types list.
The RessourceId is the unique identifier of the corresponding API object on which the event occurred. For example, for the PAYIN_NORMAL_SUCCEEDED EventType the RessourceId is the Id of the specific pay-in (the PayInId).
The Date the event took place is given as a Unix timestamp.
How it works
To set up a webhook, you can use the API or the Mangopay Dashboard (Developers > Webhooks).
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 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.
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.
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.
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.
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 list
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 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:
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:
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/ provides a temporary URL
- https://pipedream.com/requestbin provides a permanent URL if you sign up
Was this page helpful?