Webhook tutorial: What are webhooks & how to use them with the LiveChat API?

In the non-digital world, it’s the mailman who delivers our mail whenever there’s any. Imagine how incredibly inconvenient and inefficient it would be if there were no mailmen, and we would have to take a trip to the nearest post office every now and then to check if our bills have come. The same rules apply in the digital world, and one way of implementing a resource-efficient information flow is by using webhooks.

Webhooks explained

Webhooks are a way for web services to exchange information in an automated way. The automation aspect makes the whole mechanism effective because applications don’t have to periodically ask for the information they’re awaiting. Instead, they go about their business executing actions or just patiently waiting – when the information comes, they’ll know about it. They’ll get a notification: a webhook.

Let’s drill down a bit. From the technical perspective, a webhook is usually an HTTP POST request. The requester is the party sending the information to the recipient. The message is forwarded as the request body, and it’s most often the JSON format, although XML is also possible. In LiveChat, we send all webhooks in the JSON format.

When to use webhooks

Webhooks are helpful for building applications that execute particular behavior in response to various actions, allowing you to create automated flows.

Actions are usually invoked by users playing in the UI or by the application’s code. When an action happens (for example, a click), an event containing the information about the action is emitted (what was clicked, when it happened, etc.). Then, this event becomes the trigger for sending another piece of information, a webhook. The webhook is sent to a pre-defined destination, conveying the info about the initial action (the click). What happens when the webhook reaches its destination (another application) is entirely up to that application’s developer. Usually, receiving a webhook causes some behavior in the application (for instance, displaying a message).

It’s all somewhat similar to the ripple effect.

In the context of LiveChat, customer service software with live chat capabilities, we may distinguish a couple of sample use cases:

📨 Integrating LiveChat with a marketing automation tool

Event: A new visitor starts a chat.
LiveChat webhook: incoming_chat
Behavior: Adding the visitor to a contact list in the marketing automation tool.

👤 A game for customers waiting in the queue

Event: A new chat is started, but the customer lands in the queue.
LiveChat webhook: incoming_chat
Behavior: The integration detects when customers are in the queue and displays to them a game they could play in the chat widget to make waiting more pleasant.

🏷 Automatic chat tagging

Events: A customer starts a new chat. Messages are sent in the chat. The chat ends.
LiveChat webhooks: incoming_chat, incoming_event, chat_deactivated
Behavior: The integration scans messages sent in the chat in search of specific keywords or canned responses. Based on that, it tags the ended chat. The flow could be as follows:

The incoming_chat webhook notifies you when a new chat starts and provides information about initial chat events.
Then, incoming_event signals each new event sent in the chat, providing its content.
Finally, chat_deactivated tells you that the chat has ended. It’s time to tag the chat based on the keywords found in the conversation.

Configuring webhooks via the LiveChat API

Version 3.3 of the Configuration API introduced significant changes to the way LiveChat webhooks work. It is now a two-step process that involves the following:

Registering a webhook per application. (Each application is represented by Client ID, which you can find in Developer Console.)
Enabling the webhook for specific licenses.

Registering webhooks

Unlike in the Configuration API v3.2 and below, webhooks are now registered per application. Once registered, a specific webhook is assigned to the Client ID which in the request is represented by owner_client_id.

To register a webhook, use the Register Webhook method.

The registration step is crucial; without it, the LiveChat backend won’t know you’re expecting to get a webhook notification. During registration, you need to specify the endpoint where you want us to send the information (hence the url param). It’s usually your backend service. You can read more about the request parameters in the documentation.

curl -X POST \
  https://api.livechatinc.com/v3.3/configuration/action/register_webhook \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <your_access_token>' \
  -d '{
        "url": "http://myservice.com/webhooks",
        "description": "Webhook informing about new chats",
        "action": "incoming_chat",
        "secret_key": "laudla991lamda0pnoaa0",
        "owner_client_id": "asXdesldiAJSq9padj",
        "type": "license"
      }'

The type param defines one of the two possible webhooks types: license or bot. License webhooks are registered per Client ID and enabled per license. It’s the kind of webhooks this article is dedicated to. As for bot webhooks, they’re assigned to a bot, and configuring them is a three-step process: create a bot, register a webhook, and set the bot’s routing status. We’ll share more info about bot webhooks in the upcoming guides.

Let’s get back to our example. To make sure you registered the webhook correctly, call List Webhooks.

Enabling webhooks

You managed to register the webhook for your application, but does it mean that the webhook will automatically work for the licenses which installed your app? No, unless you enable the webhook first.

Calling Enable License Webhooks is rather straightforward:

curl -X POST \
  https://api.livechatinc.com/v3.3/configuration/action/enable_license_webhooks \
  -H 'Authorization: Bearer <your_access_token>' \
  -H 'Content-Type: application/json' \
  -d '{}'

You’ll need to include owner_client_id in the request body if you authorize the call using Personal Access Tokens (PATs), but keep in mind this authorization method is good for experimenting with the API or for private apps. For public (which can be paid unlike private apps) server-side applications that use webhooks, you’ll need to implement the Authorization code grant flow.

You probably noticed that Enable License Webhooks requires neither action nor the license number in the payload. That’s because the method enables all webhooks registered for a given application. Those webhooks are enabled for the license associated with the access token provided in the request.

Get started with building apps

Selling apps on the LiveChat Marketplace is an excellent way of generating passive income. Here are some resources that will help you kick off app development:

📖 Building LiveChat apps. A basic tutorial that will be helpful if you’re new to the LiveChat Platform.
🎥 Connecting LiveChat with ChatBot webinar. It covers using webhooks and authorization for server-side apps.
🗣 Join our community for developers on Discord. It’s where you can find inspiration, ask the community members for help, and exchange knowledge.