A webhook is a method we use to notify third-party applications that something has happened with Natural HR other than where that event is triggered via bulk actions such as bulk upload.

This is especially useful when using an API, as when the webhook has been received you can then call the API to perform an action.

Within Natural HR we currently support 18 webhooks covering three main actions in the system - add, update and delete.

Please note: the webhook will only fire when a core piece of information is affected - for example, when an employee is made a leaver, the system updates a number of records such as time off and training but these will not fire the time off webhooks. Likewise, if you archive a record that also will not trigger a webhook.

How do I set up webhooks?

As an administrator, go to Admin > Company > Settings > API > Webhooks and click on Add - you will then need to enter three pieces of information:

URL - this is the URL of the script which will catch the incoming webhook. Please note: this URL must be available on the internet for us to POST to.

Secret - this is your secret phrase/password which you will use to validate that the incoming webhook

Events - these are the events on which you want the webhook to trigger

Webhook formatting

Within Natural HR, our webhooks are always sent via a POST request and have a standard format consisting of a header and a body - the body will always contain JSON data.

Within the header there are two pieces of information:

Content-Type: application/JSON

Authorization: 'this will be your secret'

We strongly recommend that you check the secret each time you receive a webhook and ensure it matches the secret you are expecting - if you fail to do this then it is possible that you could receive webhooks which did not originate from Natural HR.

You can also ensure that you check the incoming webhook URL and IP address to ensure it also is the one you are expecting to receive.

Within the body, there will be JSON array which contains three pieces of information:

event: this is the event which has triggered the webhook

id: this is the ID of the object in Natural HR which caused this to trigger (for example the time off record)

employeeId: this is the employee ID of the employee in Natural HR whom the ID refers to

For example, if employee ID 12345 was updated then the body would look like:

{
  "event": "employee.update",
  "id": "12345",
  "employeeId": "12345"
}

If time off ID 23456 was deleted then the body would look like:

{
  "event": "timeoff.delete",
  "id": "23456",
  "employeeId": "1234"
}

If we cannot determine the employeeId then this will return null.