---
title: "Beneficiary Created Webhook"
source_url: https://docs.rapyd.net/en/beneficiary-created-webhook.html
lang: en
---

# Beneficiary Created Webhook

The **BENEFICIARY_CREATED** webhook is sent when the details of a beneficiary’s payout method are successfully saved.

This occurs in the following workflows:

- [Create Beneficiary](https://docs.rapyd.net/en/create-beneficiary.md "Create Beneficiary")
- [Create Extended Beneficiary](https://docs.rapyd.net/en/create-extended-beneficiary.md "Create Extended Beneficiary")
- [Create Beneficiary Tokenization Page](https://docs.rapyd.net/en/create-beneficiary-tokenization-page.md "Create Beneficiary Tokenization Page")

> **Note:**
>
> The endpoint for webhooks is unique for each client. To set up a webhook endpoint, see [Defining a Webhook Endpoint](https://docs.rapyd.net/en/defining-a-webhook-endpoint.md "Defining a Webhook Endpoint").

### Parameters

### Webhook Header Parameters

- - Content-Type
  - Indicates that the data appears in JSON format. Set to **application/json**.
- - salt
  - Random string.
- - signature
  - Signature calculated for each webhook individually.

    See [Webhook Authentication](https://docs.rapyd.net/en/webhook-authentication.md "Webhook Authentication").
- - timestamp
  - Timestamp for the webhook, in [Unix time](https://docs.rapyd.net/en/glossary.md#UUID-945d98cf-adae-e1cf-2606-c7fae8b4a7e1_unix_time "Unix time") (seconds).

### Webhook Root Parameters

- - created_at
  - Time that the webhook was created, in [Unix time](https://docs.rapyd.net/en/glossary.md#UUID-945d98cf-adae-e1cf-2606-c7fae8b4a7e1_unix_time "Unix time").

    > **Note:**
    >
    > Inside the `data` object, some webhooks have another `created_at` field that refers to a different event.
- - data
  - Contains the actual data of the webhook.

    For details, see below.
- - extended_timestamp
  - Time in milliseconds that the webhook was created, in [Unix time](https://docs.rapyd.net/en/glossary.md#UUID-945d98cf-adae-e1cf-2606-c7fae8b4a7e1_unix_time "Unix time").
- - id
  - ID of the webhook. String starting with **wh_**.
- - status
  - Status of the webhook. One of the following:

    - **NEW**
    - **CLO** - Closed.
    - **ERR** - Error.
    - **RET** - Re-sent.

    > **Note:**
    >
    > Inside the `data` object, some webhooks have another `status` field that refers to a different event.
- - trigger_operation_id
  - ID of the operation that triggered the webhook. UUID.
- - type
  - Name of the webhook type.

    > **Note:**
    >
    > The name in the Client Portal is different.

### Webhook Data Parameters

- - beneficiary_country
  - The two-letter ISO 3166-1 ALPHA-2 code for the country of the beneficiary’s bank account. The two-letter prefix of the payout method type must match the beneficiary country code.
- - beneficiary_currency
  - Currency accepted by the beneficiary’s bank account. Three-letter ISO 4217 code.
- - beneficiary_entity_type
  - Type of entity for the beneficiary. One of the following:

    - **company**
    - **individual**
- - beneficiary_extended_fields
  - When the value is **true**, the hosted tokenization page displays additional required fields.

    - Additional required fields when `beneficiary_entity_type` is **individual**: `address`, `city`, `country`, `date_of_birth`, `first_name`, `gender`, `identification_type`, `identification_value`, `last_name`, `nationality`.
    - Additional required fields when `beneficiary_entity_type` is **company**: `address`, `city`, `company_name`, `country`, `country_of_incorporation`, `date_of_incorporation`, `identification_type`, `identification_value`.

    For more information on the additional required fields, see [Create Extended Beneficiary](https://docs.rapyd.net/en/create-extended-beneficiary.md "Create Extended Beneficiary").
- - beneficiary_id
  - ID of the beneficiary. String starting with **beneficiary_**.
- - beneficiary_optional_fields
  - Additional information about the beneficiary.

    - - company_name
      - The name of the beneficiary's company. Relevant to **company** beneficiaries.
    - - first_name
      - The first name of the beneficiary. Relevant to **individual** beneficiaries.
    - - identification_type
      - Type of identification document. When `entity_type` is **company**, this field is **company_registered_number**. When `entity_type` is **individual**, one of the following values:

        - **drivers_license**
        - **identification_id**
        - **international_passport**
        - **residence_permit**
        - **social_security**
        - **work_permit**
    - - identification_value
      - The identification number of the document mentioned in `identification_type`.
    - - last_name
      - The last name of the beneficiary. Relevant to individual beneficiaries.
- - beneficiary_validated
  - Indicates whether the beneficiary has been validated. See [Validate Beneficiary](https://docs.rapyd.net/en/validate-beneficiary.md "Validate Beneficiary").
- - cancel_url
  - URL where the customer is redirected after pressing **Back to Website** to exit the hosted page. This URL overrides the `merchant_website` URL. Does not support localhost URLs.
- - category
  - The category of payout method. One of the following:

    - **bank**
    - **card** - US only.
- - complete_url
  - URL where the customer is redirected after pressing **Close** to exit the hosted page. This URL overrides the `merchant_website` URL. Does not support localhost URLs.
- - country
  - The two-letter ISO 3166-1 ALPHA-2 code for the beneficiary’s country. The two-letter prefix of the payout method type must match the beneficiary country code.
- - currency
  - Currency accepted by the beneficiary’s bank account. Three-letter ISO 4217 code.
- - entity_type
  - Type of entity for the beneficiary. One of the following:

    - **company**
    - **individual**
- - expiration
  - The page expiration date in [Unix time](https://docs.rapyd.net/en/glossary.md#UUID-945d98cf-adae-e1cf-2606-c7fae8b4a7e1_unix_time "Unix time").
- - id
  - ID of the beneficiary tokenization page. String starting with **hp_ben_**.
- - language
  - Determines the default language of the hosted page. For a list of values, see [List Supported Languages](https://docs.rapyd.net/en/list-supported-languages.md "List Supported Languages").

    - When this parameter is null, the language of the user's browser is used.
    - If the language of the user's browser cannot be determined, the default language is English.
- - merchant_alias
  - Client's name.

    Rapyd
- - merchant_color
  - Color of the call-to-action (CTA) button on the hosted page.

    To configure this field, use the Client Portal. See [Customizing Your Hosted Page](https://docs.rapyd.net/en/customizing-your-hosted-page.md "Customizing Your Hosted Page").
- - merchant_customer_support
  - Contains details of the client’s customer support. To configure these fields, use the Client Portal. See [Customizing Your Hosted Page](https://docs.rapyd.net/en/customizing-your-hosted-page.md "Customizing Your Hosted Page").

    - - email
      - Email address.
    - - url
      - URL for the client's customer support service.
    - - phone_number
      - Phone number for contacting the client's customer support service.
- - merchant_logo
  - URL for the image of the client's logo.

    To configure this field, use the Client Portal. See [Customizing Your Hosted Page](https://docs.rapyd.net/en/customizing-your-hosted-page.md "Customizing Your Hosted Page").
- - merchant_reference_id
  - Identifier defined by the client for reference purposes. Limit: 45 characters.
- - merchant_website
  - The URL where the customer is redirected after exiting the hosted page.

    Relevant when one or both of the following fields is unset:

    - `cancel_url`
    - `complete_url`

    To configure this field, use the Client Portal. See [Customizing Your Hosted Page](https://docs.rapyd.net/en/customizing-your-hosted-page.md "Customizing Your Hosted Page").
- - page_expiration
  - End of the time when the customer can use the hosted page, in [Unix time](https://docs.rapyd.net/en/glossary.md#UUID-945d98cf-adae-e1cf-2606-c7fae8b4a7e1_unix_time "Unix time"). If `page_expiration` is not set, the hosted page expires 14 days after creation.

    **Range:** 1 minute to 30 days.
- - payout_currency
  - Currency accepted by the beneficiary’s bank account. Three-letter ISO 4217 code.
- - payout_method_type
  - The payout method type selected by the customer. The two-letter prefix must match the beneficiary country code.
- - payout_method_types_exclude
  - List of payout methods that are excluded from display on the beneficiary tokenization page. Array of strings.
- - payout_method_types_include
  - List of payout methods that are displayed on the beneficiary tokenization page. Array of strings.
- - redirect_url
  - URL of the hosted page that is shown to the customer.
- - sender_country
  - The two-letter ISO 3166-1 ALPHA-2 code for the sender’s country.
- - sender_currency
  - Currency paid from the sender’s wallet. Three-letter ISO 4217 code.
- - sender_entity_type
  - Type of entity for the sender. One of the following:

    - **company**
    - **individual**
- - status
  - Status of the hosted page. One of the following:

    - **NEW** - The hosted page was created.
    - **DON** - Done. The beneficiary details were saved.
    - **EXP** - The hosted page expired.
- - timestamp
  - Timestamp for the request to create the beneficiary tokenization object page, in [Unix time](https://docs.rapyd.net/en/glossary.md#UUID-945d98cf-adae-e1cf-2606-c7fae8b4a7e1_unix_time "Unix time").
- - tokenization_page
  - ID of the beneficiary tokenization page. String starting with **hp_ben_**.

- Webhook - Beneficiary Created
- ```json
  {
      "id": "wh_f208521576cee4018ba3e539ec1c94f0",
      "type": "BENEFICIARY_CREATED",
      "data": {
          "id": "beneficiary_60374cd8dfbf1e9c2c911d4754008ddd",
          "name": "John Doe",
          "email": "john1.doe@rapyd.net",
          "country": "US",
          "category": "card",
          "currency": "USD",
          "last_name": "Doe",
          "first_name": "John",
          "card_number": "1111",
          "entity_type": "individual",
          "identification_type": "international_passport",
          "card_expiration_year": "23",
          "identification_value": "123456789",
          "card_expiration_month": "11",
          "merchant_reference_id": "john.doe",
          "default_payout_method_type": "us_mastercard_card"
      },
      "trigger_operation_id": "4493f518-0e79-4c22-aa73-b54296644c37",
      "status": "NEW",
      "created_at": 1644769993,
      "extended_timestamp": 1644769993492
  }
  ```