Contact usRequest a demo

This document describes version 5 of Unblu. If you’re using the latest major version of Unblu, go to the documentation of the latest version.

The support period for version 5 ended on 22 November 2021. We no longer provide support or updates for this version. You should upgrade to the latest version of Unblu.

Webhooks Technical Detail

RESTful services are a great way to interact with a web application and they make it easy to integrate different products with each other.

For a non-technical overview of Webhooks see Configuring Webhooks.

However, the problem with RESTful services is that they can only communicate, one-way, from the client to the server and never vice versa. In some cases it would be better to have the server inform the client about changes that the client is interested in.

Using RESTful services this could only be accomplished by polling the server regularly. Polling has several disadvantages: Firstly, it creates unnecessary network traffic, and load, on both the server and the client when nothing has changed. Secondly, changes are not directly propagated as they are delayed by the polling interval.

This is where Webhooks come in to play. The idea behind Webhooks is to provide a means to allow the web application to inform any third party about changes that have happened; as soon as they happen. To accomplish this the server / client roles are reversed. The web application server slips into the role of an HTTP client that sends updates to a third-party HTTP server.

In essence, this means that when using Webhooks, you can ask questions that are only answered when an answer exists (rather than asking the question again and again by polling the server).

In order to be able to do this the web application has to be configured to know:

  1. Where to send the information.

  2. What information to send.

Webhook Integration

Webhook Configuration

The Unblu web application server provides each account with the possibility to add several Webhook registrations. A new configuration can be added either via the user interface or via a REST call.

Each registration consists of:

  • A name

  • A description

  • An endpoint

  • The events to receive

  • An optional secret

The Endpoint

The endpoint is the full destination address (e.g., https://my.endpoint.com/unblu-Webhooks) that Unblu will send the Webhook events to. Make sure the endpoint is reachable from the collaboration server. If a proxy is necessary to access the endpoint you must remember to configure this property: com.unblu.chat.videochat.proxyUrl. (A proxy Url to be used by the Unblu server to access the TokBox cloud.)

The Event Types

unblu allows you to specify which events should be delivered to the endpoint. See the Unblu Web API for details.

Secret Key

To ensure that any Webhook event is really sent by Unblu, a secret key may (optionally) be configured.

When pushing a Webhook event Unblu generates a SHA1 HMAC of the outgoing body content using this secret key and adds it as the custom X-Unblu-Signature header.

You can verify a push came from Unblu by applying the SHA1 HMAC to the received raw request body and comparing it with the contents of the X-Unblu-Signature header. See Checking the signature.

Status

Each Webhook configuration has a status that allows you to enable or disable Webhook events being pushed to the endpoint. Additionally, if an endpoint is not reachable for a specific amount of time, the server will auto-switch the Webhook to 'disabled' to avoid trying to push events to dead endpoints.

Webhook Delivery

Triggering Webhooks

When a Webhook event is triggered internally in the server every Webhook configuration is checked to confirm that:

  1. The registration has subscribed to the triggered event.

  2. The registration status is active.

If both conditions are fulfilled a new Webhook event is generated for the configured endpoint and added to the outbound queue.

Delivery Order

The outbound Webhook queue will be processed by several Webhook workers (the number of workers is configurable).

For each endpoint the delivery order of the Webhooks is guaranteed to be the same as when they were generated.

To avoid concurrency issues the Webhook events for each endpoint will be delivered sequentially so you should at no time receive more than one Webhook push at a time.

Delivery Failures

A Webhook delivery is considered successful only if the endpoint server answers with an HTTP 2XX status code within the request timeout (also configurable).

All other HTTP response codes, as well as no response, will be considered as failures. In this case, Unblu will retry the event delivery using an exponential back off strategy:

  1. Retry after initial retry time (10s by default).

  2. If fail, double last retry time and retry.

  3. Repeat step 2 until max retry interval (3h by default) is reached and use this as the retry timeout from now on.

  4. Repeat step 3 until auto inactive timeout (48h by default) is reached. Set the Webhook configuration to 'auto-disabled' and remove all of its pending events.

As a result, if the receiving server has an internal error while processing a Webhook event, it will not receive any new events until this event was successfully delivered.

Changing Active Webhook Configurations

If one of the following properties of an active Webhook configuration is changed; all Webhook events that where placed into the outbound queue before the change will be removed.

  • endpoint

  • event types (Note that this only holds true for Webhook events in the outbound queue with event types that are no longer contained in the changed registration’s event types.)

  • secret

Receiving Unblu Webhooks

Headers

Each Webhook delivery has the following headers:

  • User-Agent 'Unblu-Hookshot' (may be configured)

  • X-Unblu-Event The event type. Use this to filter and dispatch the incoming events.

  • X-Unblu-Event-ID A unique ID for this Webhook event. This will stay the same for retried deliveries of the same event.

  • X-Unblu-Delivery A unique ID for this delivery, you should never receive two requests with the same delivery ID.

  • X-Unblu-Signature The SHA1 HMAC of the outgoing body content using the configured secret key as password. See Checking the signature

Payload

The payload of all Unblu Webhook events is in JSON format.

Common rule: All Webhook events of one event type always contain the same data structure. There are some common properties that every Webhook event contains and individual data for each event type:

{
    "timestamp": 1494485391283,             // the unix time in millis when the event was generated.
    "eventType": "chat_request.created",    // the event type.
    "accountId": "wZvcAnbBSpOps9oteH-Oxw",  // the id of the account that this event originated from.
    ...                                     // individual event properties
}

Check the Web API for more details on the different event types and their payloads.

Best Practices

When receiving and handling Webhooks there are several best practices that you should take into account.

Do the heavy lifting asynchronously: Try to keep the response time of your server as low as possible and ensure that all heavy computation and I/O access is handled asynchronously. This allows Unblu to deliver its Webhooks in a timely fashion and avoids the delivery being marked as failed due to timeout.

Check the event type before accessing data: Make sure to check if the event type of the push you received really is the one you are expecting (to avoid your code from breaking if, for some reason, you get an unexpected event).

Disable your Webhook registration if you have planned down times: If you know that your server is going to be down for a while, disable the Webhook configuration to make sure that the server does not run into one failed delivery after another filling up the queue, (and also to avoid being flooded with events once your server is up again).

Check if you have received the Webhook already If you want to make sure that you do not process one Webhook event more than once, create a list of the last x calls and drop all requests with the same delivery id.

Checking the signature

There are a lot of methods to compute the SHA1 HMAC signature. You should take the one that is suitable for your context (depending of the language and the framework you are using).

Bellow some examples:

In Java using the commons-codec:commons-codec:1.14 library:

import java.util.Objects;

import org.apache.commons.codec.digest.HmacAlgorithms;
import org.apache.commons.codec.digest.HmacUtils;

public class Check {

    /**
     * Checks the signature of the received message is correct or not
     * @param headerValue the value of the X-Unblu-Signature header
     * @param body the content of the POST request
     * @param secret the value of the secret configured in the Unblu server
     * @return if the signature is matching the expected one or not
     */
    public static boolean isSignatureCorrect(String headerValue, String body, String secret) {
        String signature = new HmacUtils(HmacAlgorithms.HMAC_SHA_1, secret).hmacHex(body);
        return Objects.equals(headerValue, signature);
    }
}

Example with Node.js:

import { createHmac } from 'crypto';

// Given 'secret' containing configured value in the Unblu server
// Given 'req' the http-request object:
const signature = createHmac('sha1', secret).update(req.rawBody).digest('hex');
const isSignatureValid = (req.headers['x-unblu-signature'] != signature);

Troubleshooting Webhooks

Ping Event

After configuring your Webhook you can check if everything works by sending a 'ping' event. You can either do this in the Webhook UI or via a REST call using the Webhook Registration service. See Configuring Webhooks to send a ping from the Webhook user interface in the Agent Desk.

Delivery Log

If you have problems receiving the Webhook events or want to track what the server sent out to your endpoint, you can check the Webhook delivery log which lists all the details of each Webhook delivery, including request and response headers and payloads.