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.

Configuring Webhooks

When you want to 'ask questions' of the system the normal behavior is for the client to 'poll' the server for the required information. Webhooks offer an alternative to polling.

Polling vs. Webhooks

'Polling' is when the kids are in the back of the car and they won’t stop asking 'Are we there yet?' (You are the server and they are the clients - the only way for them to get the answer they want is by asking…​ and asking…​ and asking, until the answer happens to be 'yes'.)

Using a 'Webhook' means the driver (server) only has to tell the kids (clients) when they’ve arrived. No matter if you ask a billion times, the answer is only 'yes' once. Webhooks eliminate the need to keep asking.

This is why polling is a very inefficient means to ask questions of a server and why you should seriously consider framing some requests as Webhooks. Webhooks eliminate redundancy by cutting web traffic and reducing server load. Webhooks also ensure that the information is returned as soon as it exists and is not tied to any polling schedule. This is especially useful if you should decide to integrate Unblu statistical data into your own real-time analytical models.

The decision as to whether to use a Webhook or not is entirely dependent on how the question you are asking is framed within your 'broader system'. It is quite difficult to think of use cases where polling is technically 'better' than using Webhooks. But it may be that you already have processes in place where 'polled' data is integrated into larger models according to predefined schedules and you want to continue that polling strategy with Unblu data.

This section will describe how you can set up a Webhook from within the Agent Desk. See Webhooks Technical Detail for more on best practices and technical considerations.

How it works: The collaboration server functions as a client to a web server that you define. The collaboration server can then connect to that server to handle the requests.

Create a Webhook

You need at least 'Admin' credentials to perform the following steps.
webhooks new webhook 1

  1. In the Agent Desk select Webhooks then click the New webhook button. A modal window slides in from the right.

    webhooks new webhook 2
    Each new Webhook is set to 'Enabled' by default. This is useful if you ever want to switch off the Webhooks without losing any configuration values.

  2. Fill-in the Name and Description fields then, in the Endpoint URL field, add the URL to your web server (e.g., https://my.endpoint.com/unblu-Webhooks)

    The endpoint is the full destination address to which Unblu will send the Webhook events.

  3. Select the checkbox(es) representing the event(s) you want to subscribe to. (In order to find out what each check box represents simply hover over the icon hover over information icon.)

    For example, you may want to select the session-lifecycle event in order to receive information each time a new session is created or an existing session is terminated. The services you can subscribe to are self-explanatory; for example, adding or deleting users, teams, domains or names areas.

    webhooks new webhook 3

  4. When you have selected all the services you wish to subscribe to you may want to (optionally) add a 'secret key' in the Secret key text box. See Secret Key for more details on this added security measure.

  5. When you are done configuring the Webhook click Save.

    webhooks new webhook 4

    Now you can see the Webhook, and the events you have subscribed to, listed in Webhooks.

    In order to test if the Webhook works:

    webhooks new webhook 5 ping

  6. Click the queue 6 downwards-pointing chevron then, from the list, select Send ping event. A dialog box asks you to confirm.

    webhooks new webhook 6 ping

  7. Click OK. You will see a notification telling you that the server has been pinged.

    In order to see the log:

  8. Again, click the queue 6 downwards-pointing chevron then, from the list, select Open delivery log

    webhooks new webhook 7a delivery log

    Using this log you can check whether the ping was successful or not. And, using the Edit Webhook button, you can also edit the Webhook directly from here.

    Note that you can use the filters at the top of this modal window to set filters and/or sort by:

    • Response code

    • Time

    • Event

    • Retry number

    The log lists all the details of each Webhook delivery, including request and response headers and payloads.

    + image::../imgs/webhooks-new-webhook-8-see-delivery-log.png[]

  9. Click on an entry to see more detail in the log.

  10. When you are done configuring Webhooks click OK.