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 event occurs and the information with new data comes, they'll know about it. They'll get a notification: a webhook request.
Let's drill down a bit. From the technical perspective, a webhook is usually a regular HTTP request with a POST method. The requester is the party sending the information to the recipient. The message is forwarded as this HTTP request body, and it's most often the JSON format, although XML formats are also possible. In LiveChat, we send all webhook requests in the JSON format.
So, when we talk about webhooks, we're generally talking about a way for one service to notify another service of some event or change that has occurred by sending real-time data. In most cases, these notifications are implemented using HTTP requests. Specifically, webhooks rely on HTTP POST requests, where the payload of the request contains information about the event that triggered the webhook.
It's worth noting that instead of a standard HTTP POST request, other protocols could also be used in some cases. For example, some services might use WebSockets, yet the HTTP requests are still the most common in web development and the easiest to implement in webhook integrations.
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.). As this event occurs, it becomes the trigger for sending another piece of information, a webhook request. The webhook is sent to a pre-defined destination endpoint, conveying the info about the initial action (the click).
What happens when the webhook reaches its destination webhook URL (another application) is entirely up to that application's developer. Usually, receiving a webhook request causes some behavior in the application (for instance, displaying a message with some new data).
You can compare the webhook request process 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 for webhook integrations:
📨 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_chatwebhook request notifies you when a new chat starts and provides information about initial chat events. - Then,
incoming_eventsignals when each new event occurs in the chat, providing its content. - Finally,
chat_deactivatedtells 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. Now, you need to register a webhook per application, as each application is represented by the Client ID, which you can find in the Developer Console.
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 receive webhook requests. During registration, you need to specify the endpoint where you want us to send the information (hence the webhook url param). The webhook URL is usually your backend service. You can read more about the request payload 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.
💡 All your registered webhooks will be automatically enabled for each license that installs your app and grants it access. The Disable License Webhooks should be called explicitly when there is a need to disable some webhooks.
Hassle-free way to test webhooks requests
To use webhooks, you typically need to provide a webhook URL that the other application can send the HTTP request to. Let's take a look at how to use the webhook.site — a website where you can test and post webhook requests.
webhook.siteis an independent online system that allows you to receive webhook requests and test your webhook implementation without needing to set up your own server. Here, you can simply send a single webhook request and preview the webhooks payloads before you configure the same webhook request in other apps.
To test your webhooks, simply provide the webhook URL from webhook.site during webhook registration in LiveChat and wait until the events occur so LiveChat can send data — you can also trigger the events yourself!
It's very helpful to test your webhooks before you dive into the implementation details as it helps you to deeply understand the specifics of a webhook from a certain webhooks provider you want to integrate with.
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.
