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?