ResourcesWebhooks

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=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+ 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
  • Using a valid SSL certificate (for HTTPS)
  • Able to handle the expected request volume
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 an 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
1{
2    "Url": "https://webhook.site/e1def644-2cee-4669-a4a6-b6ceeacc621b",
3    "Status": "ENABLED",
4    "Validity": "VALID",
5    "EventType": "USER_ACCOUNT_ACTIVATED",
6    "Id": "hook_m_01JQW43GW82MJ23HB8Y6B3JZ72",
7    "Tag": "Created using the Mangopay Postman collection",
8    "CreationDate": 1743626814,
9    "Email": "tech@example.com"
10}
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 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).

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 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 or PUT Update a 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:

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

API request
1{
2    "Validity": "VALID"
3}

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

API request
1{
2    "Status": "DISABLED" // "ENABLED"
3}

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

Guide

See the list of available event types

Endpoints

The Hook object