Setting up Webhook Integrations
Set up as follows;
Payload URL – this is the url where our api will send the message to
Content type – can only be application/json. All our payloads are in JSON format. The receiving service must accept a JSON payload
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.
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
