Skip to main content

Manage webhooks 

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

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

For an example, see the webhook tutorial.

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.
  • If you want the data to be sent to a specific URI, consider using a webhook instead.
Feature access

Only admins and Application admins have access to this feature.

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 > Usage & Limits.

List webhooks​

You can list all the webhooks in your account. Draft webhooks also appear in this list.

To list all the webhooks in your account:

  1. On the leftmost menu, click Account.
  2. Click Tools > Webhooks.

The Webhooks page contains the following information:

ColumnDescription
NameName, description, and state of the webhook.
VerbMethod of the HTTP request: POST, PUT, GET, DELETE or PATCH.
ApplicationsThe Applications in which the webhook is available.
CopyClickable icon that allows you to copy the 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 > Tools > Webhooks.

  2. To create a webhook from scratch, click Create Webhook. Alternatively, click a draft webhook to continue creating it.

  3. 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.

  4. (Optional) In Description, type a description for the webhook.

  5. 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.

  6. 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.

  7. In the Credentials section, select the credentials to use for authentication.

  8. In the Headers section, add any request headers required by the receiving service as key-value pairs.

    To add a header, click Add Header. You can add more than one header. To remove one, click .

    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 the same way as in the payload. For example:
      1. Create a custom attribute with the Application entity called url.
      2. In your Applications, define the attribute value: https://webhook.site/application1.
      3. In the URL field of your webhook, reference the attribute: ${$Application.Attributes.url}.

  9. (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 Parameter. To remove one, click .

  10. (Optional) In the Payload section, enter and format the payload in JSON format. See Define the webhook payload.

    Tip

    You can reference custom attributes as shown below:

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

  11. (Optional) In the Preview section, review the payload that is sent in the webhook.

  12. Validate the URL and headers by sending a test request. To do this, in the Test section, click Test Webhook.

  13. Click Create Webhook.

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

Define the webhook payload​

You can define the payload of a webhook when you create one. The payload can contain the following references:

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, add a parameter named bodyText:

    Creating a webhook request

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

    {
      "body": "${$bodyText}"
    }
    Important

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

  3. Create a rule that uses this webhook as an effect and define the bodyText value to use:

    Using a webhook as an effect.

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 to apply their value in the webhook payload when a request is sent.

  • To reference a Built-in attribute, use the <entity>.<attributeName> pattern in the webhook payload.
    • For example, reference Integration ID (Customer Profile) as "my_prop": "${$Profile.IntegrationId}".
  • To reference a Custom attribute, use the <entity>.Attributes.<attributeName> pattern in the webhook payload.
    • For example, reference myAttribute (Coupon) as "my_prop": "${$Coupon.Attributes.myAttribute}".
Tip

  • To view the available attributes, see Manage attributes.

  • If you are referencing attributes from the 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 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 with no response code.

Edit a webhook​

To edit a webhook:

  1. On the leftmost menu, click Account.
  2. Click Tools > Webhooks.
  3. Click the name of a webhook to open it.
  4. 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 in a 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.

  2. Click Tools > Webhooks.

  3. Next to the webhook you want to copy, click .

    Tip

    To copy a webhook that you're editing, in the Copy section, click Copy Webhook.

  4. 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.
  2. Click Tools > Webhooks.
  3. Click the name of a webhook to open it.
  4. In the Delete section, click Delete Webhook.
  5. In the confirmation window, click Delete Webhook.
Note

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

  • The webhook is referenced in a 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.
On this page