Webhooks

Besides using the RESTful API for interacting with Help Lightning, it is also possible to listen for events from Help Lightning using webhooks. Webhooks allow you, as an integrator, to subscribe to specific Help Lightning events. When one of those events is triggered, Help Lightning will send an HTTP POST payload to your webhook’s configured URL. Some examples of what webhooks can be used for are:

• integrate a phone queue system into Help Lightning’s signaling system
• automatically add tags to a call when it starts
• pull data when a video call is completed
• send out a notification when a specific user joins a call
• automatically archive recordings to a learning management system

Before you can use a webhook, you MUST have a publicly accessible web server that has a valid TLS certificate!

If you are interested in just testing out how webhooks work, we find that using ngrok is a simple way to define a public HTTP endpoint and either redirect it to a local non-public server or just capture the data for testing.

Webhooks can be added using either the web administration interface at helplightning.net or through the API.

The first step is to log into helplightning.net with an Administrator Account.

Before you can see the Developer Settings, you must first enable the Developer Tools option. To do so, click on your name in the top right corner and choose Settings.
Then enable the Developer Tools slider:
Click on Administration⇒Workspace Settings, then click on the new Developer tab.
Under Webhooks, click the Add Webhook:
First you will need to add a Payload URL. This is the domain and path of your public HTTP server. Help Lightning will send a POST payload to this url for the event specified:
Select the Event type from the pull down. All webhook categories tied to this event type will be sent to the specified payload url. If you want to receive multiple event types, you can add multiple webhooks:
It is highly recommended that you add a Secret. Without this, you won’t be able to validate that the payload came from Help Lightning. This should be a long random string.
Choose Add Webhook

To test your webhook, you will need to generate a corresponding event in the Help Lightning system.

You can also use the Help Lightning API to create and modify your webhooks. Please see:

• Creating a Webhook API
• Getting Webhooks API
• Modifying a Webhook API
• Deleting a Webhook API

Currently, Help Lightning supports three classes of webhooks:

• session
• call
• workbox

The session class of webhooks are used for session signal events. Signaling is the pre-call setup that consists of ringing and answering/declining the call. These can be used to send out real time ringing notifications (through Push Notifications) or to integrate with a phone queuing system.

The call class of webhooks are used for video call related events. Common events include when a video call starts or stops, a participant joins or leaves, or meta-data, such as an attachment is added to the video call.

The workbox class of webhooks are used for workbox related events. Common events include when a workbox created or closed.

Once your public server is configured, it will listen for any payload sent to your endpoints. For security purposes, you probably only want to listen to payloads that can be verified to come from Help Lightning. This is done by setting a secret token when configuring your webhook and validating the signature of the payload.

When a secret token is set, Help Lightning uses it to create a hash signature with each payload. This hash signature is included with the headers of each request as x-helplightning-signature.

Help Lightning uses an HMAC hex digest with a shared secret (your secret token) to compute the hash of the message. It is then possible for you to compute this same signature using your secret and validate that it matches the header. If the header doesn’t match, then the message should be ignored.

A good tutorial on how to validate the signature can be found on GitHub’s Webhook Documentation.

If an event happens in Help Lightning, and your server is unavailable for some reason, then Help Lightning will retry the event. Help Lightning will use a standard back-off algorithm and try up to 25 times before discarding the message.

If your sever returns a 4xx error, then Help Lightning will not retry the event. If you server returns too many 4xx errors, then Help Lightning may automatically disable your webhook.

Every event will include a header, x-helplightning-delivery, that includes a globally unique UUID. In the ideal world, a duplicate message should never happen, but due to network issues or a misconfiguration of a web server, it is possible that Help Lightning will not get a valid response and decide to retry.

To handle duplicate messages, you can keep a short-lived cache of the x-helplightning-delivery values, and if you see an event that has a value that is already in your cache, then you can ignore that event.

The following describes the available webhooks and their payloads. All Help Lightning webhooks include the following headers:

• x-helplightning-event-type: This is the type of message. Currently it can be either session, call or workbox
• x-helplightning-event-category: This is the subcategory. Based on the type of message, there are different subcategories, as outlined below.

Session type webhooks are tied to Help Lightning call setup, which is called signaling. This is the aspect of ringing a device, then responding to that request.

Session webhooks can be utilized to send out real time notifications to your client applications using TCP socket, Websockets, push notifications, or any other method of your choosing.

Session webhooks can also be utilized for advanced routing, such as integrating with an existing phone queuing system.

All of these webhooks will have an x-helplightning-event-type of session.

A video_requested x-helplightning-event-category is used to notify a user that someone is requesting a call with them.

A video_request_accepted x-helplightning-event-category indicates a user has accepted the request to join video. This is intended for the original requestor.

A video_request_declined x-helplightning-event-category indicates a user has declined the request to join video. This is intended for the original requestor.

A video_request_canceled x-helplightning-event-category indicates the original requestor has canceled their outgoing call request. This is intended for the original requestee.

You will see this event generated when a requstee accepts or declines a video request. This is because the requestee can potentially be logged into multiple devices and receiving an incoming call on each device. When the requestee accepts or declines a call on a specific device, this event will be sent out with that device id filled in. This allows you to then send this event to the requestee’s other devices so that they stop ringing.

Call webhooks are tied to video call events. This is when a video call is started/stopped, users enter/leave a video call, or a video call has attachments added to it.

This can be useful for many reasons, including:

• Linking call data to an external CRM
• Seeing which if your experts are on a call in real time
• Capturing real time statistics of calls into your own business intelligence systems
• Automatically archiving recordings to a learning management system

All of these webhooks will have an x-helplightning-event-type of call.

A started x-helplightning-event-category indicates that a video call has been started. Not all of the participants are known yet. This will also link a call back to a session_id, which can then be linked to a signaling request (if there was one).

The ended x-helplightning-event-category indicates that a video call has completed.

The participant_joined x-helplightning-event-category is sent out each time a participant joins a video call. Use the call_id to link this to a started or ended event.

It is possible for a participant to join and leave a call multiple times!

The participant_left x-helplightning-event-category is sent out each time a participant leaves a video call. Use the call_id to link this to a started or ended event.

It is possible for a participant to join and leave a call multiple times!

The attachment_created x-helplightning-event-category indicates that a new attachment for this call has been uploaded. Attachments are typically screen captures or recordings. This can be used to automatically archive artifacts associated with a call to an internal data storage system.

Some attachments, such as a recording, will be created AFTER the call has completed.

The event does not include the attachment. You will need to use the id from the attachment object and query the Help Lightning API to get the download URL.

Workbox webhooks are tied to workbox events. This is when a workbox is created/closed.

All of these webhooks will have an x-helplightning-event-type of workbox.

A created x-helplightning-event-category indicates that a workbox has been created.

The closed x-helplightning-event-category indicates that a workbox has been closed.