Skip to main content
POST
/
v2.01
/
{ClientId}
/
hooks
{
    "Url": "https://example.com",
    "EventType" : "PAYIN_REFUND_SUCCEEDED",
    "Tag": "Created using the Mangopay API Postman Collection"
}  

{
    "Url": "https://example.com",
    "Status": "ENABLED",
    "Validity": "VALID",
    "EventType": "PAYIN_REFUND_SUCCEEDED",
    "Id": "hook_m_01J8F5RK4R43AYWD8XVG9RSYDT",
    "Tag": "Created using the Mangopay API Postman Collection",
    "CreationDate": 1727086218
}

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.

Caution – Setting email for consecutive failures after April 2026In Production, if your platform had VALID Hook objects before April 2, 2026, then Mangopay automatically populates the Email property on new Hooks with the previously used global address unless and until you set it proactively using this endpoint.If you send the Email on a POST or PUT request, other new Hooks created without the Email do not populate the Email automatically and do not emit alerts in case of consecutive failed notifications or if the Hook becomes INVALID.Platforms integrating after April 2, 2026 must proactively set the Email to receive alerts.Read more about this change →

​
Body parameters

​
EventType
string
required
Allowed values: An EventType listed in the event types listThe type of the event.
​
Url
string
required
Max. length: 255 charactersThe URL to which the notification is sent.
​
Tag
string
Max. length: 255 charactersCustom data that you can add to this object.
​
Email
string | null
Format: A valid email addressThe Email address to which alerts are sent in case of consecutive failed notification attempts.Caution: Mangopay may populate this property automatically if your platform had webhooks integrated in Production before April 2, 2026. If so, setting the Email on a single Hook stops this automatic population for any new Hooks you create - read more.For all platforms, if this property is returned null then no alerts are sent but the Hook still becomes INVALID after 100 consecutive failed notifications.

​
Responses

​
Url
string
Max. length: 255 charactersThe URL to which the notification is sent.
​
Status
string
Returned values: DISABLED, ENABLEDWhether the hook is enabled or not.
​
Validity
string
Returned values: VALID, INVALIDWhether the hook is valid or not. Once INVALID (following unsuccessful retries) the hook must be disabled and re-enabled.
​
EventType
string
Returned values: An EventType listed in the event types listThe type of the event.
​
Id
string
Max length: 128 characters (see data formats for details)The unique identifier of the object.
​
Tag
string
Max. length: 255 charactersCustom data that you can add to this object.
​
CreationDate
Unix timestamp
The date and time at which the object was created.
{
    "Message": "One or several required parameters are missing or incorrect. An incorrect resource ID also raises this kind of error.",
    "Type": "param_error",
    "Id": "829f2782-85a9-45b1-a2bd-993b0978c5bc",
    "Date": 1690295313.0,
    "errors": {
        "EventType": "A hook has already been registered for this EventType"
    }
}  

{
    "Url": "https://example.com",
    "Status": "ENABLED",
    "Validity": "VALID",
    "EventType": "PAYIN_REFUND_SUCCEEDED",
    "Id": "hook_m_01J8F5RK4R43AYWD8XVG9RSYDT",
    "Tag": "Created using the Mangopay API Postman Collection",
    "CreationDate": 1727086218
}

{
    "Url": "https://example.com",
    "EventType" : "PAYIN_REFUND_SUCCEEDED",
    "Tag": "Created using the Mangopay API Postman Collection"
}