Skip to main content

Webhooks

A webhook allows a Talon.One Application to send information in real-time to third-party software. A webhook is configured to be triggered by a specific event and sends an HTTP request.

In the case of Talon.One, you can create webhooks to communicate information from the Talon.One Rule Engine to an external system. A webhook is always triggered as an effect inside a rule.

This a generic topic about webhooks. To see a concrete 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.
note

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.

Creating a webhook​

To create a webhook:

  1. In the lower-left corner, click Account > Tools > Webhooks > Create Webhook.

  2. In Properties, enter the webhook's basic properties.

    • In Name, type a name for the webhook.
    • (Optional) In Description, type a description for the webhook.
    • In Applications, select the Applications in which you want the webhook to be available.

  3. (Optional) In Parameters, define the parameters in your webhook that can be populated when a rule is executed. This allows you to share data from the Rule Engine with the recipient of the webhook.

    • In Param type, set the parameter type (string, number, boolean, or time).
    • In Param name, type the name of the parameter.
    • In Param description, add a description for the defined parameter.

  4. In Request, define the other properties of the webhook.

    • In Verb, choose the type of request (DELETE, GET, PATCH, POST, or PUT).
    • In URL, set the URL of the receiving service.
    • In Header, add a potential header to the webhook. You can add more than one header.
    note
    • Some servers may not accept the request without an appropriate Header value.
    • In the URL and Header fields, you can use custom attributes the same way as in the payload. For example:
      1. Create an Application custom attribute called url.
      2. In your Applications, define its value: https://webhook.site/application1.
      3. In the URL field of your webhook, reference the attribute: ${$Application.Attributes.url}.

  5. For PATCH, POST, and PUT, requests, in Payload, enter the request payload of the webhook.
    You can reference attributes and parameters in the payload as shown below:

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

  6. Click Save.

note

See the webhook tutorial for a concrete example.

Defining a webhook's payload​

When you define the payload of your webhook you can use parameters and attributes:

  • A parameter is a value you set in a rule and that gets inserted in your payload when the rule is executed.
  • An attribute is a value that is stored inside Talon.One. It can come from the integration layer via the Update customer profile or Update customer session endpoints such as the customer's location or the session's value.

Using parameters in a webhook​

A parameter allows you to set its value from a rule.

For example, if we want to send an email via a webhook, we can set the body of the email from a rule:

  1. Create a parameter named bodyText:

    Creating a webhook request

  2. In the Request payload field, paste the following payload to store the bodyText parameter value in a body property in the request:

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

  3. Create a rule that uses this webhook as an effect and set the bodyText parameter value:

    Using a webhook as an effect.

Alternatively, we can share data from Talon.One without relying on data set in a rule using attributes.

Using attributes in a webhook​

You can include attributes in your webhook payload.

Viewing available attributes​

In Account > Tools > Attributes, you can view the available attributes.

There are two categories of attributes: Built-in and Custom. The way you use them in your payload depends on their category.

Using a custom attribute​

To use a custom attribute, use the <entity>.Attributes.<attributeName> pattern.

Example: myAttribute (Coupon) becomes "my_prop": "${$Coupon.Attributes.myAttribute}".

Using a built-in attribute​

To use a Built-in attribute, use the <entity>.<attributeName> pattern.

Example: To use Integration ID (Customer Profile), use Profile.IntegrationId.

note

If you are using the Attributes page to find entity names, rename the following entities as follows:

  • CustomerProfile to Profile
  • CustomerSession to Session

Examples:

  • CustomerProfile.name becomes "my_prop": "${$Profile.name}".
  • CustomerSession.CurrentLocation becomes "my_prop": "${$Session.CurrentLocation}".

To see a webhook example, see the webhook tutorial.

Webhook retry policy​

When a webhook cannot be sent because of 5xx or 429 Too Many Requests responses, progressively delayed resend attempts are made up to 10 times or until a 2xx response is received, whichever occurs earlier.

The progressive delay between each resend attempt is calculated using errorCount ^ 4 + 3 seconds, where errorCount represents the number of failed attempts.