Displaying external events on Kayako timelines with webhooks

Along with our Zapier integration and the full Kayako API, webhooks offer another way to capture customer events in external apps and display them on Kayako conversation and user timelines. Each webhook consists of a label, a description, and an auto-generated API token. You can then take that label and token to any of your favorite APIs and use it as a destination to send notifications about customer activity.

Any information that comes in about a customer via a webhook is then displayed on the user's timeline, and the conversation timeline for any open conversations the user has. Webhooks are a powerful way to give your team that much more context about what your customers are getting up.

In this article we'll look at what webhooks are used for, walk you through creating one in Kayako, and point you to some resources for using them with your favorite external APIs.

Understanding how to use webhooks

Let's look at an example. Say you use Zuora to handle your billing, and you want to send a notification to Kayako anytime a customer's payment doesn't go through. To make that easier, you can create a new webhook within Kayako, which will give Zuora's API a place to send its billing notifications.

Although you can accomplish the same thing using the Kayako API proper, webhooks have two distinct advantages:

• They're more secure. With a regular API call, you have to authenticate using your username and password, which gives the external system access to any part of the Kayako API. With a webhook, you authenticate using a token instead, which exposes only that particular corner of the API to the external system.
• They're easier to get started with. If you're new to working with APIs, webhooks are a great place to start. Each webhook is a mini-exercise in how APIs talk to each other.

There are two elements to using webhooks with Kayako. First, you'll need to create a new webhook from the admin area. Then, you'll need to tell your external API to send event information to your new webhook. Let's have a look in detail.

Creating a new webhook

A webhook, in Kayako, is basically just a way to define an access point that an external API can use to push information into Kayako. Building a webhook consists of giving it a label — which the external API will use to identify it — and adding a description so you know what it's for. When you save your webhook, Kayako will automatically generate a token that the external API can use to authenticate itself before it sends any information.

NOTE: To create webhooks in Kayako, you will need an administrator account with the 'Manage channels' permission.

To add a new webhook:

1. Sign in to Kayako and go to the admin area.
2. Click Webhook on the sidebar.
3. Click the New webhook button.
4. Add a Label for your webhook. This is how the external API will identify the webhook later.
5. Add a Description for your webhook. This is just for you and your team, to help you keep track of what each webhook you create is for.
6. Click the Save button.
7. You'll see the page reload and a Webhook token appear. The external API will need this token to get access to your new webhook. When you're building your API call, come back here and click the Copy to clipboard button to copy the token.

And that's it! You're new webhook is ready to go. Read on to learn more about pushing information to it from external APIs.

Using your new webhook with an external API

We'll be adding lots more detail here soon, but for now, if you're looking to use your new webhook with an external API, our developer docs about using webhooks should be helpful: https://developer.kayako.com/api/v1/event/events/#Incoming-webhook