Webhooks are essential to the mechanisms of intelliHR integrations. Webhooks can be used for a variety of functions or activities, such as alerting people or other systems when a certain action has taken place in intelliHR. It will usually instruct the person or other system to complete an action as a result.
This article covers:
Webhooks Definition
A webhook is a mechanism that allows intelliHR to send a notification to a client when a specific event has occurred. A webhook can be used to alert a client application when a certain action has taken place in intelliHR, such as the creation of a new job or the completion of a form.
Webhooks are typically used in cases where the client application needs to be notified of an event in real-time, without the need for the client to continuously poll intelliHR for updates. This allows for a more efficient communication between the client and intelliHR, as the intelliHR only needs to send a notification when an event of interest has occurred.
To use a webhook, the client application must first register a webhook URL with intelliHR. This URL is a endpoint on the client side that intelliHR can send a notification to when the specified event occurs. When the event occurs in intelliHR, the server sends a HTTP POST request to the registered webhook URL, along with a payload of data related to the event. The client application can then use this data to take appropriate action, such as updating its own data or triggering some other action.
Types of Webhooks
intelliHR has several different types of webhooks that can be triggered at different times, including:
-
At processing time: These webhooks are triggered when a specific action occurs in the system, such as when a person is created or when a job is updated (
person.created,job.update_scheduled). -
Scheduled offsets: These webhooks are triggered at a specific time in the future, based on an offset from a reference point. For example, a webhook might be triggered a certain number of days before a company's start date (
job.company_start_date_upcoming). -
Removal: These webhooks are triggered when an object is deleted from the system. For example, a webhook might be triggered when a person is deleted (
person.deleted).
💡 A full list of webhook events available in intelliHR can be accessed here.
IP Whitelisting for Webhooks
intelliHR uses the following IP ranges to send webhooks from:
For customers based in Europe and North America:
- 54.74.150.228/32
- 54.73.108.157/32
- 54.246.31.155/32
All other customers:
- 54.66.48.1/32
- 54.79.136.162/32
- 54.253.224.28/32
Using Webhooks
Subscribing to a Webhook via the API
To subscribe to a webhook using the intelliHR API, the client application must first register a webhook URL with the server. This is done by making an HTTP POST request to the webhooks endpoint.
"url": https://api.intellihr.io/v1/webhooks
"method": 'POST'
"headers": {
"Content-Type": 'application/json',
"Accept": 'application/json',
"Authorization": `Bearer ${apikey}`,
"Tenant": tenantname
}
"body": {
"url": "http://example.com",
"webhookEvent": "person.created",
"isEnabled": true,
"source": "custom"
}
Using the Webhook Payload
intelliHR uses skinny webhooks. A skinny webhook is a type of webhook that only includes minimal information in its payload, rather than sending the full data associated with the event that triggered the webhook.
{
"id": "f9e721c2-a936-47eb-970e-801e4fe8a9bd",
"event": "person.created",
"timestamp": "2022-12-20T03:31:32Z",
"links": {
"self": "https://api.intellihr.io/v1/people/f9e721c2-a936-47eb-970e-801e4fe8a9bd",
"selfEncoded": "https://api.intellihr.io/v1/people/f9e721c2-a936-47eb-970e-801e4fe8a9bd"
}
}
The idea behind skinny webhooks is to reduce the amount of data that is transmitted over the network and improve the efficiency of the webhook system. Instead of sending the full data for an event, intelliHR only sends a notification containing a the personID of the person that was created.
In order to return the information about the person that was created. You will need to perform a subsequent HTTP GET request to the relevant endpoint. In the case of person.created, we will perform a GET request on the people endpoint. If we were using the job.created event, we would use the jobs endpoint to perform our request.
Use the self link returned on the webhook in the url of the following GET request.
"url": https://api.intellihr.io/v1/people/{id}
"method": 'GET'
"headers": {
"Content-Type": 'application/json',
"Accept": 'application/json',
"Authorization": `Bearer ${apikey}`,
"Tenant": tenantname
}
Tip: For information on how to use webhooks in intelliHR, contact your friendly intelliHR Integration Team! You can reach them at integrations@intellihr.com