An overview of Customer Thermometer webhooks

Put simply, webhooks allow customers to automatically trigger an action with a 3rd party application, when something happens inside their Customer Thermometer account.

Webhooks are available across all Customer Thermometer plans, as well as to trialists too.

This guide shows you how to set up webhooks.

Examples of usage

Before we explain how to set up webhooks, let’s look at some ways they can be used.

Usage examples

1) You could display incoming Customer Thermometer ratings and comments inside a Slack channel (with the help of Zapier):

2) You could trigger automated response emails to disappointed customers (also with the help of Zapier):

3) For those 3rd party tools where we don’t yet write responses back directly into it – you now can (with the help of Zapier).

In the example below, we’re pushing ratings and comments into Freshdesk’s excellent support desk.

4) In addition, you can now connect Customer Thermometer responses and comments into legacy systems – create ‘endpoints’ within your internal helpdesk and push your responses directly into it.

In short, the world’s your oyster when it comes to triggering events, based on incoming Customer Thermometer ratings.

An introduction to webhooks

If you’d like to know what they are and how they work, take a look at the guide below.

What is a webhook?

A webhook is a mechanism of providing a reaction to an event. They are also sometimes referred to as a web callback or HTTP push API.

Customer Thermometer webhooks can provide other applications with real-time information. They deliver data to other applications as it happens, meaning you get data immediately.

Webhooks are a useful tool for executing an action in another app or system after a specific response event happens – for example. when a customer hits a gold star, or leaves a comment on a red response.

They can be used as alerts to keep your systems and partner applications in sync with response events that occur within Customer Thermometer.

Customer Thermometer can send webhooks to any publicly accessible server.

When an event in Customer Thermometer triggers a webhook (e.g., a red response is received), Customer Thermometer will attempt to send this notification to the endpoint(s) you specify. You can specify an unlimited number of endpoints for any combination of Thermometers.

A single event may be sent to many webhook endpoints.

Note: Your endpoint must be reachable at ports 80 (HTTP) or 443 (HTTPS).
Webhook event data is sent as JSON via the IP address: 109.169.28.117
Your endpoint must respond within 5 seconds
Your endpoint must respond with a 2XX status code (e.g., 200, 201, 204, etc.)

What types of webhook can I trigger?

Webhooks can be registered for any combination of these events:

  • Gold response
  • Green response
  • Yellow response
  • Red response
  • Comment left against a gold response
  • Comment left against a green response
  • Comment left against a yellow response
  • Comment left against a red response

Are webhooks secure?

You have the option to include Basic Authentication (Basic Auth) when setting up your webhooks. It allows you to provide the username and password associated with the HTTP endpoint (this is not your Customer Thermometer username and password).

Almost all web servers can be configured to require a user name and password for access to a URL. When webhook data is sent, the Basic Auth fields are included in the header of the HTTP request. Using Basic Auth increases the security of your webhook event data and ensures that the data delivered originates from Customer Thermometer.

Verifying your webhook

As an additional layer of security, each webhook includes a X-Ct-Hmac-Sha256 header which is generated using your unique shared secret, along with the data sent in the request.

You can see your shared secret at the bottom of the ‘View endpoint’ page.

To verify that the request came from Customer Thermometer, compute the HMAC digest according to the following algorithm and compare it to the value in the X-Ct-Hmac-Sha256 header. If they match, you can be sure that the webhook was sent from Customer Thermometer and the data has not been compromised.

Below is a simple example in PHP script of how one might verify a webhook request:

<?php

define('CT_WEBHOOKS_SECRET', 'my_shared_secret'); // e.g. 02ee43a0c82e42c3f79701cc7db8389f3fcd4ac1dace9ec92592220964e75d59

function verify_webhook($data, $hmac_header, $date_header)
{
$content = "Date: " . $date_header . "\n" . $data;
$calculated_hmac = base64_encode(hash_hmac('sha256', $content, CT_WEBHOOKS_SECRET, true));
return ($hmac_header == $calculated_hmac);
}

$hmac_header = $_SERVER['HTTP_X_CT-Hmac_SHA256'];
$date_header = $_SERVER['HTTP_DATE'];
$data = file_get_contents('php://input' [^] [^]);

$verified = verify_webhook($data, $hmac_header, $date_header);
error_log('Webhook verified: '.var_export($verified, true)); //check error.log to see the result

?>

CSRF tokens

If you’re using Rails, Django, or another web framework, your site may automatically check that every POST request contains a CSRF token.

This is an important security feature that helps protect you and your users from cross-site request forgery attempts.

However, this security measure may also prevent your site from processing legitimate webhooks. Therefore, you will need to disable ‘protect from forgery’ on any sites run these various web frameworks.

1) Overview of webhooks admin

You can reach the webhooks screen via to the top menu.

Initially it will be empty of course. Over time, it might look something like this:

The screen shows each individual webhook created, the endpoint URL and the Thermometers which will trigger it. The dark grey chevron icon will expand the list to show the Thermometers included within that webhook.

Note that Email Thermometers are designated by the yellow envelope icon, Embedded Thermometers are designated by the blue tag icon.

Note the pagination at the bottom.

The second tab shows the event log – a record of every webhook which has fired:

Again, note the pagination at the bottom.

2) How to create a new webhook

Once you’ve decided what you’d like to trigger, based on a response or comment from a particular Thermometer(s), you will need to firstly add a new endpoint. Secondly, you’ll attach that endpoint to a specific Thermometer or set of Thermometers.

Once that process is complete, each time a response is received by one of those Thermometers, the webhook will fire to that endpoint.

This guide explains how.

Configure a webhook

You can configure your webhooks by clicking on “Webhooks” in the top right hand corner of the screen when you’re logged into your account.

Click “Add new endpoint

Give it a name, and then enter the URL (http:// or https://) where you want to receive notifications. We strongly recommended using HTTPS wherever possible.

To get started with webhooks – we recommend looking at Zapier. Click here for our guide.

Next, choose the events that you want to trigger your webhook. You can select any combination you wish.

In the example below, I have chosen to trigger automatic autoresponder emails on receipt of a yellow or red alert:

Authentication

You next have the option to include Basic Authentication (Basic Auth) when setting up your webhooks. It allows you to provide the username and password associated with the HTTP endpoint (this is not your Customer Thermometer username and password).

Almost all web servers can be configured to require a user name and password for access to a URL. When webhook data is sent, the Basic Auth fields are included in the header of the HTTP request.

Using Basic Auth increases the security of your webhook event data and ensures that the data delivered originates from Customer Thermometer.

Note, if you’re using Zapier, this isn’t needed.

Testing

The final stage of the process is to click “Test fire webhook“. This will confirm the endpoint is configured correctly.

If the test doesn’t reply with a Status 200 (delivered) then something’s wrong. Check your URL is correct and that the Basic Auth details are correct if you’re using them.

Advanced testing

If you want to capture the contents of a webhook to examine them, the easiest way is use a service like RequestBin which will capture the result and let you view it in a browser. RequestBin allows you to create a URL that will collect any requests made to it. You can then inspect your requests and see the values returned. The URL provided is temporary and can only be used for 20 requests or for 48 hours (whichever comes first).

Linking Thermometers

Before clicking on the Linked Thermometers tab, ensure you’ve test fired your webhook and you receive a 200 status.

Until this is complete, you will not be able to link Thermometers to the endpoint.

When you’re ready, click on the Linked Thermometers tab. It will look something like this:

The interface is intuitive. Simply scroll down to the the Thermometer or Thermometers you’d like to associate with this endpoint and click the chevron to transfer it to the box on the right:

Note you can include as many as you wish.

In some scenarios, only one Thermometer might be included. In others, there might be several. Flexibility is everything!

You can use the Selection radio buttons at the top and also remove Thermometers from the ‘included’ box, but selecting them and clicking the chevron to send it back the other way.

When you’re happy with your selection, click the “Save webhook” button.

3) Working with webhooks

Receiving a webhook

Once you register an endpoint URL within your webhook, we will issue an HTTP POST request to the URL specified every time that the event(s) you selected occur against the Thermometers that you linked.

The request’s POST parameters will contain JSON data relevant to the event that triggered the request.

Responding to a webhook

Your webhook acknowledges that it received data by sending a “200 OK” response.

Any response outside of the 200 range will let Customer Thermometer know that you didn’t receive your webhook.

We try to send the webhook again every hour, over the next 24 hours, after which it is deleted.

Viewing events.

You can see the status of your triggered webhooks by going to the Event log and filtering as required:

Here you can see the webhooks that have been triggered and their status. You can dive into the detail (by clicking on the “DETAILS” link and see the contents of the JSON that was sent along in the webhook body.

We store successful (200 OK) event contents, for 20 days.

4) Using Zapier with Customer Thermometer webhooks

The Zapier SaaS app is the best way to get started with webhooks. It allows you to simply (10 min setup) connect Customer Thermometer to 100’s of other apps. This means you can use ratings and comments to trigger all kinds of other automated events and to push ratings into other systems with ease.

We explain more below.

Zapier basics

Zapier is a tool for primarily non-technical users to connect together web apps, such as Customer Thermometer and Slack.

An integration between two apps is called a Zap. A Zap is made up of a Trigger and one or more Actions or Searches.

Whenever the trigger happens in one app (such as a Customer Thermometer response), Zapier will automatically perform the actions or searches in another app in order (such as posting the response inside Slack).

Zaps are very lightweight and easy to set up. Zaps do not import or export old data (they only operate on new items created after the Zap is enabled). Zaps are also not kept in sync (“two way syncing”) after the Zap is triggered.

How to push ratings into Slack using Zapier

**COMING SOON**

Need more help or advice? Get in touch.