Overview

Along with Zapier's integration with Kayako and the full Kayako API, webhooks offer another way to capture customer events in external apps and display/update them on Kayako conversations 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 to
• You won't be able to send replies or add notes to conversations but you can use webhooks to send updates about external events to Kayako user timelines.

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.

Solution

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.

1. First, you'll need to create a new webhook from the admin area.
2. 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.

Adding Meeting Event Information using cURL

After creating your webhook, use the following cURL to add external events to a user's timeline.

curl -X POST https://<subdomain>.kayako.com/api/v1/webhook/<webhook ID>/incoming
-d '{"event":"<event name>", "properties":{"url":"<event URL>",
"icon_url":"<event icon URL>","accountID":"<account ID>",
"type":"meeting"}, "user":{"email:"<email address>", "full_name":
"<name>"}}' -H "Content-Type: application/json"

Replace the items in "<>" to add the external event to the user's Timeline. This information will be displayed for all these users' conversations so that agents will be able to see this update while checking the conversations.​