HaloITSM

HaloITSM Guides

Documentation to assist with the setup and configuration of the HaloITSM platform

Guides > Webhook Integration

Webhook Integration

In this guide we will cover:

- Basic webhook configuration

- Batching (Introduced in v2.164)

- Toggle whether the ID or display value of a field is used in the payload (v2.178+)



Webhooks can be created in Halo to retrieve and post data to specific endpoints, for example to send data to an external application. 


To create a webhook in Halo head to configuration > Integrations > Webhooks > new. 


Basic Webhook configuration

Payload URL – This is the URL our API will send the message to.

Webhook type – 'Standard webhook' should be selected unless you are setting up an integration with a pre-configured webhook. All our payloads are in JSON format. The receiving service must accept a JSON payload.

Method - If the webhook being used to retrieve (GET) data or send data from Halo to another application (POST). 

Authentication – No Authentication if none required on the receiving service. Basic Authentication allows input of username and password if the receiving service requires Basic Authentication.


Use lightweight logs - When enabled this webhook will use lightweight logs, this means a full log will not be stored for the webhook in the database. This is used to improve performance when sending webhooks with very large payloads as it reduces the amount of data stored in the database. When enabled you cannot re-send wehooks from logs. 


Events – This is a list of events that trigger the webhook to be sent. These are basically the same as Halo Notification profiles and work the same way – ie “New Ticket Logged”, “Ticket Reassigned” etc. Like notifications you can put conditions on these. You need at least one event per Webhook profile.


Once the conditions of an event are met, our API will then queue a HTTP Post to the Payload URL containing the ticket and action objects where applicable. The response from the receiving API will then be recorded and will be viewable from the Deliveries tab of the webhook. Examples of this are in the below screenshots.


Fig 1. Webhook payload



Fig 2. Response


If when an event happens, a record appears in the deliveries tab, our applications work is done. It’s then in the hands of the customer to implement something to accept the payload and do what they want to do with the payload at the destination.


Batching (Introduced in v2.164)

Utilising the batching options in Webhooks will mean that less webhooks will be sent, improving the performance of these both in Halo and applications that receive these batched webhooks.


To enable batching for a webhook, go to the webhooks configuration and set the "Batching" setting to one of the following options;

Group occurrences of the same event in the same delivery

Group occurrences of the same event type in the same delivery

Group occurrences of any event in the same delivery


The "Batching" setting defaults to "One delivery for each occurrence of an event" which is where there is a single webhook delivery for each event occurrence.


The Batching setting is only available in configurations where;


  • Payload is not "Full object with linked objects"
  • Webhook type is "Standard webhook"
  • The method is "Post"
  • When batching is enabled, the webhook's payload will be a JSON array of objects rather than a single JSON object. Before enabling batch sending, please ensure that whatever application is receiving your webhooks is able to handle the request being in this format.


Additional settings available for batching are as follows;


"Batch wait seconds" - batched webhooks wait a few seconds for more events that can be included in the same webhooks. This determines how long to wait before delivering. This can be anywhere from a few seconds to several minutes. Note if the wait time is more than 5 minutes the delivery time will not be accurate as it uses a different mechanism to send.

"Maximum items per batch" - allows you to put a limit on how many occurrences of an event should be included in a single webhook


Toggle whether the ID or display value of a field is used in the payload (v2.178+)

When you are configuring a custom payload for a webhook you will notice the setting shown in figure x when configuring fields to be included in the payload. 

Fig 3. Send ID value instead of the Display value


When this setting is enabled the database ID of the value entered in the field here will be sent in the payload. The ID is the unique identifier for this field value. 


If unchecked the display name of the field value will be sent instead.


Note: This is only applicable to single select fields. 



Popular Guides

Pin It on Pinterest