Webhooks

When creating rules for a campaign, sometimes you want a rule to execute an effect outside of the Talon.One API. For example, you might want to make a rule that when a customer has spent $500 they should receive an email which says 'Thank you for shopping with us!' In the Talon.One developer tools, you can create a rule effect which sends information to another web application, also called a Webhook.

#What is a Webhook?

A Webhook is a way for one application to send another application information in real-time. A Webhook sends an http request (POST, PUT, GET, DELETE, PATCH) usually triggered by an event. With the Talon.One Rule Engine, you can create rules whose conditions trigger Webhooks.

#Handling with errors

If a Webhook fails or receives an error, it will be triggered 10 times with an ascending amount of time between the attempts.

#Configuring a Webhook

For some practice, this section will walk through setting up a test Webhook using this nice tool requestb.in. requestb.in allows you to use a URL to inspect http requests. All you have to do is go to the requestb.in site and create a RequestBin which will provide you with a URL. Once you have sent http requests, you can check the results at this URL.

First you want to navigate to the Webhook page in Developer Tools on your Talon.One account. Here you enter the title of the Webhook, the application where it will be used, any parameters (in our example email text which is a string), the request (in this case a POST request to your RequestBin URL), any headers (add one with Content-Type: application/json), and a payload. A payload is information that is sent along with the request.

In this test, add the text below as the payload:

{
            "Name": "${$Profile.Attributes.Name}",
            "Email": "${$Profile.Attributes.Email}",
            "EmailText": "${$EmailText}"
}

By adding this payload text, the request will send the customer name, customer email address, and the text which the email will contain. Also be sure to tick the box next to the Title and Application which says 'Display in Rule Editor.'

After saving the Webhook, you can go to the Rule Editor and create this example. You can drag and drop the Total Sales Value as the condition and set the value as greater than or equal to 500. Lastly, you can add the Webhook as the effect and enter in the email text 'Thank you for shopping with us!' Now you want to test the rule and the Webhook.

#Using parameters within a Webhook

Within the webhook configuration page, you are able to use profile- and campaign-parameters. You can use these parameters in the Payload and the URL. Unlike webhook related parameters you pass in the effect of a rule, you need a route to access them. For instance if you want to use a profile related parameter:

{${$Profile.Attributes.Email}

A campaign-related parameter is reachable by:

{${$Campaign.Attributes.Email}

#Testing a Webhook

With the API Tester, you can create a customer account to test the rule you have created. First, you want to set the application, the path as /v1/customer_profile, and the URL Params to 'test'. The advocateId can have any value. For the Attributes, you should add a Name and Email which you can also set to any value. These attributes will be the information stored for the account, and this is the information the Webhook needs to send. The curl should look similar to this:

curl -X PUT  -H 'Content-Type: application/json' \
    -H 'Content-Signature: signer=1; signature=e4b6cceecaac21d5137537e82df5bf20' \
    -d '{
          "advocateId": "advocateId",
          "attributes": {
                    "Name": "name",
                    "Email": "email"
          }
}' 'http://talon.one/v1/customer_profiles/NewCustomerProfile30'

You can copy the curl and execute it in terminal. An error message will be returned if the curl did not succeed. This has created a customer profile you will use to test the Webhook.

Next you want to create a customer session that will trigger the rule. This time you should select the path /v1/customer_sessions. The URL Params can have any value. Under properties you only need the profileId set to 'test' and the total set to 500 or more. The curl should look something like this:

curl -X PUT  -H 'Content-Type: application/json' \
    -H 'Content-Signature: signer=1; signature=84fcc52185fa7a9d5961d19c99f3cd1c' \
    -d '{
          "profileId": "test",
          "total": 510,
          "attributes": {}
}' 'http://talon.one/v1/customer_sessions/NewCustomerSession53'

You can copy this and execute it in your terminal. An error message will be returned if the curl did not succeed. This has created a customer session that will ping the web client.

Next, you can check if the Webhook was triggered and successful by going to the RequestBin URL. When you refresh the page, you should see a POST request was made with a Raw Body that matches the payload information: Name, Email, EmailText.

This is the process for creating, utilizing, and testing a Webhook. Any of the attributes in the Attribute Library can be used in Webhook payloads and URLs.