Skip to main content
New user request Sign in Visit humanforce.com

How to use Humanforce HR Webhooks

 

 

Webhooks are essential to the mechanisms of Humanforce HR 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 Humanforce HR. It will usually instruct the person or other system to complete an action as a result. 

This article covers:

Webhook Definition

A webhook is a mechanism that allows Humanforce HR 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 Humanforce HR, 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 Humanforce HR for updates. This allows for a more efficient communication between the client and Humanforce HR, as the Humanforce HR 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 Humanforce HR. This URL is a endpoint on the client side that Humanforce HR can send a notification to when the specified event occurs. When the event occurs in Humanforce HR, 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

Humanforce HR has several different types of webhooks that can be triggered at different times, including:

  1. 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).

  2. 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).

  3. 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 humanforce hr can be accessed here.

IP Allowlisting for Webhooks

Humanforce HR 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 Humanforce HR 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

Humanforce HR 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, Humanforce HR 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 Humanforce HR, log a ticket with our Support Team 

 

 

 

 

Related articles