> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.mangopay.com/api-reference/webhooks/hook-object/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.mangopay.com/_mcp/server.

# The Hook object

### Description

A webhook is a technical approach that allows Mangopay to submit a notification to other applications whenever a specific event occurs.

The Hook object allows you to receive notifications, to a URL you define, that are triggered by a specific event type. You can set up only one URL for each event type.

> **Check**
>
> **Best practice – Idempotent hook processing**
>
> The retry feature (i.e., new notification if your app was unreachable) can set the hook to `INVALID`. We strongly recommend you make your event processing idempotent to avoid receiving duplicate notifications for the same events.

### Attributes

### Schema (`HookResponse`)

```yaml
components:
  schemas:
    Id:
      type: string
      description: >-
        Max length: 128 characters (see [data
        formats](/api-reference/overview/data-formats) for details)


        The unique identifier of the object.
      title: Id
    Tag:
      type: string
      description: >-
        Max. length: 255 characters


        Custom data that you can add to this object, such as unique identifiers
        in your system. To store multiple values, you can serialize them into a
        single string, for example a JSON object:
        `"{\"id_1\":AB123,\"id_2\":DE456}"`.
      title: Tag
    CreationDate:
      type: integer
      description: Unix timestamp (UTC) of the date and time the object was created.
      title: CreationDate
    HookResponse:
      type: object
      properties:
        Url:
          type: string
          description: |-
            Max. length: 255 characters

            The URL to which the notification is sent.
        Status:
          type: string
          description: |-
            **Returned values:** `DISABLED`, `ENABLED`

            Whether the hook is enabled or not.
        Validity:
          type: string
          description: >-
            **Returned values:** `VALID`, `INVALID`


            Whether the hook is valid or not. Once `INVALID` (following
            unsuccessful retries) the hook must be disabled and re-enabled.
        EventType:
          type: string
          description: >-
            **Returned values:** An `EventType` listed in the <a
            href="/webhooks/event-types">event types list</a>


            The type of the event.
        Id:
          $ref: '#/components/schemas/Id'
        Tag:
          $ref: '#/components/schemas/Tag'
        CreationDate:
          $ref: '#/components/schemas/CreationDate'
        Email:
          type: string
          description: >-
            Format: A valid email address


            The `Email` address to which alerts are sent in case of [consecutive
            failed notification
            attempts](/webhooks#notification-retries-and-failure).


            **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](/webhooks#transition-from-default-email-april-2026).


            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.
      title: HookResponse
```

### Related resources

#### [Guide](/webhooks)

Learn more about hook notifications