A webhook is a way for HR-ON Staff to notify your application about events in real-time. It allows you to receive notifications about events automatically when they occur in HR-ON Staff, without having to poll the API for updates continuously. Webhooks are useful for automating data synchronization between HR-ON Staff and your internal systems or to trigger actions in your application based on specific events that occur in HR-ON Staff.
For example, you can set up a webhook to notify your application whenever a new employee is created, or when an employee's information is updated.

• A webhook must be verified in order to receive any events, including forced test events from the Trigger Webhook endpoint.
• Your endpoint must be publicly accessible and reachable from the internet. It cannot be a localhost or private IP address.
• Your endpoint must be able to handle POST requests and must respond with a 200 OK status code to received events.
• Your endpoint must respond to events within 10 seconds.
• If your specified URL is either unreachable or fails to respond with a 200 OK status in time, then after 10 consecutive failures, the webhook will be deactivated and must be re-verified.
• All webhook events are sent as POST requests to the specified URL.
• All webhook events contain your specified token in the X-HR-ON-Token header.

To create a webhook, you need to send a POST request to the Create Webhook endpoint with the following parameters:

• endpoint: The URL where the webhook will send data.
• eventNames: An array of events that will trigger the webhook.
• token: A unique token that will be sent with the webhook request to verify its authenticity.

Example creation request:

POST /webhooks
Host: https://webhook.hr-on.com/v1
Content-Type: application/json

Body: {
  "endpoint": "https://your-webhook-receiver-url.com",
  "eventNames": ["EmployeeCreated", "EmployeeUpdated"],
  "token": "your_unique_token_here"
}

You can see the full list of response properties in the Create Webhook endpoint documentation, but the most important one is id, which is the unique identifier for the webhook you just created. You will need this ID to manage your webhook in the next steps.

After creating the webhook, you need to verify it using the Verify Webhook endpoint.
The verification process involves your endpoint receiving a POST request with a payload containing a randomly generated 64 byte string, which your endpoint must return in the response body.

Example verification request:

POST /webhooks/{webhookId}/verify
Host: https://webhook.hr-on.com/v1
Content-Type: application/json

If everything is set up correctly, and your endpoint responded with a 200 OK status and the same 64 byte string in the response body, your webhook will be verified.

You can test your webhook by triggering a test event using the Trigger Webhook endpoint. This will send a sample event to your webhook endpoint, allowing you to verify that it is working correctly.

Example test request:

POST /webhooks/{webhookId}/trigger
Host: https://webhook.hr-on.com/v1
Content-Type: application/json

Body: {
  "eventName": "EmployeeCreated",
}

Your endpoint will receive a POST request with a sample payload matching what you would receive in a real event. You will always receive the following properties in the payload:

• message - A user friendly message describing the event.
• eventName - The name of the event that was triggered.
• sentAt - The date and time when the event was sent.

You will also receive one of the following properties, depending on the event name:

• employeeId - The ID of the employee that was created or updated.
• departmentId - The ID of the department that was created or updated.
• documentId - The ID of the document that was uploaded or deleted.

Do note that any IDs from these test events are fake and will not correspond to any real data in your HR-ON Staff account.

When your endpoint receives a webhook event, you are then able to consume it and take action based on the event. The payload will contain the same properties as the test event, but with real data. The most common use case is to update your internal systems with new data from HR-ON Staff, when an employee is updated.
Below is an example of how this simple flow could look like:

You receive a webhook event with the following payload:

{
  "message": "An employee has been updated",
  "eventName": "EmployeeUpdated",
  "sentAt": "2025-06-17T11:00:00.000Z",
  "employeeId": "3fe2987b-ef4e-4b7c-b321-89585e2a4178",
}

You then make a request to the HR-ON Staff API to get the employees data:

GET /employees/3fe2987b-ef4e-4b7c-b321-89585e2a4178
Host: https://api.hr-on.com/v1/staff
Authorization: Bearer your_access_token_here

You can then use the data from the response to update your internal systems with the new employee data.