# Manage webhooks

> A webhook allows a Talon.One [Application][app] to send information in real-time to third-party software.

> For the complete documentation index, see [llms.txt](https://docs.talon.one/llms.txt).

You can [configure a webhook](#create-a-webhook) to be triggered
by a specific [event][event] and send an HTTP request containing a payload
that [you define](#define-the-webhook-payload)
to a URL of your choice. A webhook is always triggered as an
[effect][webhook effect] inside a [rule][rule].

For an example, see the [webhook tutorial](/docs/dev/tutorials/create-a-webhook.md).

:::note Custom effect versus webhook
Custom effects and webhooks allow you to send data from Talon.One to the platform of
your choice.

Before choosing one over the other, consider the following:

- If you prefer receiving the data in your integration layer and parsing it like any other
  effect, use a [custom effect](/docs/product/account/dev-tools/manage-custom-effects).
- If you want the data to be sent to a specific URI,
  consider using a [webhook](/docs/product/account/dev-tools/manage-webhooks) instead.
:::

<FeatureAccessInfoBox>
Only admins and Application admins have access to this feature.
</FeatureAccessInfoBox>

:::note
- To create and manage webhooks, ensure you are the admin or Application admin for every Application the webhook is connected to.
- Your contract can determine the maximum number of webhooks that you can create.
You can find this information in the Campaign Manager,
in <Account className="icon"/> **Account** > **Usage & Limits**.
:::

## List webhooks

You can list all the webhooks in your account. <NotificationCardTag tag="Draft" /> webhooks
also appear in this list.

To list all the webhooks in your account:

1. On the leftmost menu, click <Account className="icon"/> **Account**.
1. Click <Tools className="icon"/> **Tools** > **Webhooks**.

The **Webhooks** page contains the following information:

| Column           | Description                                                                      |
| ---------------- | -------------------------------------------------------------------------------- |
| **Name**         | Name, description, and state of the webhook.                                     |
| **Verb**         | Method of the HTTP request: **POST**, **PUT**, **GET**, **DELETE** or **PATCH**. |
| **Applications** | The Applications in which the webhook is available.                              |
| **Copy**         | Clickable icon that allows you to [copy the webhook](#copy-a-webhook).        |

:::note
If you are an Application admin, the list does not contain webhooks connected to individual
Applications unless you have access to at least one of those Applications.
:::

## Create a webhook

To create a webhook:

1. In the lower-left corner, click <Account className="icon"/>
   **Account** > <Tools className="icon"/> **Tools** >
   **Webhooks**.
1. To create a webhook from scratch, click <Add className="icon" /> **Create Webhook**.
   Alternatively, click a draft webhook to continue creating it.
1. In **Name**, type a name for the webhook.

   :::tip
   To save the webhook as a draft, type the name and click **Save Draft**.
   You can continue creating it later.
   :::

1. (Optional) In **Description**, type a description for the webhook.
1. In the **Connected Applications** section, select the Applications where
   you want the webhook to be available.
   By default, it is available for use in all Applications.
1. In the **Request details** section, do the following:
   - In **Verb**, select the type of request (**DELETE**, **GET**, **PATCH**, **POST**, or **PUT**).
   - In **URL**, enter the URL of the receiving service.
     Only HTTP and HTTPS protocols are supported.
1. In the **Credentials** section, select the [credentials](/docs/product/account/credentials.md) to use for authentication.
1. In the **Headers** section, add any request headers required by the receiving
   service as key-value pairs.

   To add a header, click <Add className="icon" /> **Add Header**.
   You can add more than one header. To remove one, click <Delete className="icon" />.

   :::note
   - By default, the following read-only headers are included:
     - `Content-Type: application/json`
     - `X-UUID: (generated)`. When sending the webhook, `(generated)` is replaced with a unique
       identifier.
   - In the **URL** and **Header** fields,
     you can use [custom attributes](#use-attributes-in-the-webhook-payload) the same way
     as in the [payload](#define-the-webhook-payload).
     For example:
       1. Create a [custom attribute](/docs/product/account/dev-tools/manage-attributes.md)
          with the **Application** entity called `url`.
       1. In your Applications, [define the attribute value](/docs/product/applications/use-attributes.md#add-custom-attributes-to-an-application): `https://webhook.site/application1`.
       1. In the **URL** field of your webhook, reference the attribute: `${$Application.Attributes.url}`.
   :::

1. (Optional) For **PATCH**, **POST**, and **PUT**, in the **Parameters** section, define the parameters
   in your webhook that can be populated with a value when a rule is successfully evaluated.
   This allows you to share data from the Rule Engine with the webhook recipient.

   - In **Type**, select the data type of the parameter.
   - In **Name**, type the name of the parameter.
   - (Optional) In **Description**, add a description for the parameter you're defining.

   You can add more than one parameter.
   To add a parameter, click <Add className="icon" /> **Add Parameter**.
   To remove one, click <Delete className="icon" />.

1. (Optional) In the **Payload** section, enter and format the payload in JSON format.
   See [Define the webhook payload](#define-the-webhook-payload).

   :::tip
   You can reference [custom attributes](/docs/product/account/dev-tools/manage-attributes.md)
   as shown below:

   ```json
   {
      "attributePayload": "${$Profile.Attributes.Name}",
      "parameterPayload": "${$ParameterName}"
   }
   ```
   :::

1. (Optional) In the **Preview** section, review the payload that is sent in the webhook.
1. Validate the URL and headers by sending a test request. To do this,
   in the **Test** section, click <Compass className="icon" /> **Test Webhook**.
1. Click **Create Webhook**.

The webhook is created, and [the list of webhooks][listing webhooks] is displayed.

## Define the webhook payload

You can define the payload of a webhook when you [create one](#create-a-webhook).
The payload can contain the following references:

- **[Parameters](#use-parameters-in-the-webhook-payload)**:
  A value that you define in a rule and is inserted in the webhook payload
  when the rule is successfully evaluated.
- **[Attributes](#use-attributes-in-the-webhook-payload)**:
  A value that is stored inside Talon.One, for example, the customer's location
  or the session's value. It can come from the integration layer
  via the [Update customer profile](/integration-api#tag/Customer-profiles/operation/updateCustomerProfileV2)
  or [Update customer session](/integration-api#tag/Customer-sessions/operation/updateCustomerSessionV2) endpoints.
  See the [Attributes][attributes] page.

### Use parameters in the webhook payload

Use parameters to define a value in the webhook payload when you call the webhook
in the effect.

For example, imagine you want to send an email via a webhook.
You can define the body text of the email in an effect while calling the webhook:

1. In the webhook [you create](#create-a-webhook), add a parameter named `bodyText`:

   

1. In the **Payload** section, paste the following payload to store the `bodyText`
   parameter value in a property named `body` in the request:

   ```json
   {
     "body": "${$bodyText}"
   }
   ```

   :::important
   The parameter value (`bodyText`, in this case) must match the name you gave it in step 1.
   :::

1. [Create a rule][create rule] that uses this [webhook as an effect][webhook effect]
   and define the `bodyText` value to use:

   

Alternatively, you can share data from Talon.One without relying on a value defined
in the webhook effect by [using attributes](#use-attributes-in-the-webhook-payload).

### Use attributes in the webhook payload

Use [attributes][attributes] to apply their value in the webhook payload
when a request is sent.

- To reference a <Attribute name="Built-in" type="builtin" /> attribute,
use the `<entity>.<attributeName>` pattern in the webhook payload.
  - For example, reference <Attribute name="Integration ID (Customer Profile)" />
as `"my_prop": "${$Profile.IntegrationId}"`.
- To reference a <Attribute name="Custom" type="custom" /> attribute,
use the `<entity>.Attributes.<attributeName>` pattern in the webhook payload.
  - For example, reference <Attribute name="myAttribute (Coupon)" type="custom" />
as `"my_prop": "${$Coupon.Attributes.myAttribute}"`.

:::tip
- To view the available attributes, see [Manage attributes][managing attributes].
- If you are referencing attributes from the
  [Attributes](/docs/product/account/dev-tools/manage-attributes.md#display-attributes) page,
  rename the following entities in the webhook payload:

  - Rename `CustomerProfile` as `Profile`.
    - For example, `CustomerProfile.name` becomes `"my_prop": "${$Profile.name}"`.
  - Rename `CustomerSession` as `Session`.
    - For example, `CustomerSession.CurrentLocation` becomes `"my_prop": "${$Session.CurrentLocation}"`.
:::

## Webhook retry policy

[Progressively delayed][exp backoff] resend attempts are made up to 10 times
or until a `2xx` response is received, whichever occurs first.
Resend attempts are made when a webhook request cannot be sent for the following reasons:

- `5xx` response codes.
- `429 Too Many Requests` response code.
- There's no response at all.

Webhook requests have a response timeout of 10 seconds.
Requests that time out are [logged][logs] with no response code.

## Edit a webhook

To edit a webhook:

1. On the leftmost menu, click <Account className="icon"/> **Account**.
1. Click <Tools className="icon"/> **Tools** > **Webhooks**.
1. Click the name of a webhook to open it.
1. Make the required changes and click **Save**.

:::note
You can only view a webhook and **cannot** edit it if one of the following applies:

- The webhook is [referenced][effect] in a [campaign][campaign].
- You are an Application admin, and the webhook is connected to all Applications.
- You are an Application admin, and the webhook is connected to at least one Application
  for which you do not have access rights.

In these cases, all input fields are disabled.
:::

## Copy a webhook

You can copy all the parameters and request details
of a webhook to a new webhook. There are no dependencies between the original and the copy.

To copy a webhook:

1. On the leftmost menu, click <Account className="icon"/> **Account**.
1. Click <Tools className="icon"/> **Tools** > **Webhooks**.
1. Next to the webhook you want to copy, click <Copy className="icon" />.

   :::tip
   To copy a webhook that you're [editing](#edit-a-webhook),
   in the **Copy** section, click <Copy className="icon" /> **Copy Webhook**.
   :::

1. Enter the basic properties of the copy, and click **Copy Webhook**.

## Delete a webhook

To delete a webhook:

1. On the leftmost menu, click <Account className="icon"/> **Account**.
1. Click <Tools className="icon"/> **Tools** > **Webhooks**.
1. Click the name of a webhook to open it.
1. In the **Delete** section,
   click <Delete className="icon" /> **Delete Webhook**.
1. In the confirmation window, click <Delete className="icon" /> **Delete Webhook**.

:::note
You **cannot** delete a webhook if one of the following applies:

- The webhook is [referenced][effect] in a [campaign][campaign].
- You are an Application admin, and the webhook is connected to all Applications.
- You are an Application admin, and the webhook is connected to at least one Application
  for which you do not have access rights.
:::

## Related pages

- [Create webhooks](/docs/dev/tutorials/create-a-webhook.md)
- [Use effects](/docs/product/rules/effects/use-effects.md)
- [Display webhook logs](/docs/product/account/logs/webhook-logs.md)

[campaign]: /docs/product/campaigns/overview.md
[effect]: /docs/product/rules/effects/use-effects.md#use-webhooks
[listing webhooks]: /docs/product/account/dev-tools/manage-webhooks.md#list-webhooks

[exp backoff]: https://cloud.google.com/pubsub/docs/subscription-retry-policy#exponential_backoff
[event]: /docs/dev/concepts/entities/events.md
[attributes]: /docs/dev/concepts/attributes.md
[managing attributes]: /docs/product/account/dev-tools/manage-attributes.md
[app]: /docs/product/applications/overview.md
[rule]: /docs/product/rules/overview.md
[create rule]: /docs/product/rules/create-and-manage-rules.md
[webhook effect]: /docs/product/rules/effects/available-effects.md#webhooks
[logs]: /docs/product/account/logs/webhook-logs.md