HaloCRM

HaloCRM Guides

Guides > Webhook Integration

Webhook Integration

In this guide we will cover:

- Configuring the Webhook Basics

- Batching

- Toggle whether the ID or display value of a field is used in the payload



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


Configuring the Webhooks Basics

To create a webhook, head to Configuration > Integrations > Webhooks > New. 


  • Webhook Name: Used as a reference in the UI.
  • Payload URL: The URL the Halo 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: 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 webhooks from logs. 


  • Payload: Sets the payload type. Each will contain an ID, notification ID, escmsg ID, event name, webhook ID, object ID, and timestamp properties.
    • Small object with key fields only: Includes the basic properties of the entity rather than all.
    • Full object with linked objects: Includes everything relevant.
    • Event information only (v2.214.1+): Includes the object ID and event name.
    • Use a custom payload


  • 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 – i.e. “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

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:


  • One delivery for each occurrence of an event: Default with no batching. Sends a single webhook delivery for each occurrence.
  • Group occurrences of the same event in the same delivery: Grouping by event.
  • Group occurrences of the same event type in the same delivery: Grouping by event type.
  • Group occurrences of any event in the same delivery: Complete grouping.


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

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