Before you begin

This guide includes API call examples. Note that while you don’t need to use service users to receive webhook events, to access data via the API, you must define a service user in Bob and grant it the necessary permissions, as demonstrated below.

Notes:

Refer to the Migrate to webhooks v2 for detailed steps on adapting your integration and FAQs.

Migration requires using Bob's Public API. If you are new to Bob's API, first read Getting started with Bob API.

This guide provides examples of how to call the APIs but does not cover all event types and all the data you may need to retrieve for processing a webhook event.

For update events, you need to parse the fieldIds included in the webhooks event's payload and include them in the API request body to retrieve the updated values.

If migrating from Webhooks v1, ensure that permissions are configured correctly for the service user and that you identify all required fields beforehand to avoid missing critical data.

Employee event example

To handle employee events in webhooks v2, note that the employee identifier appears in the payload for employee 'created' or 'updated' events. If it's an update, the payload includes the updated field IDs. Use the employee ID in the endpoint URL and the field IDs in the request body to retrieve the latest values.

employee.created

Action	Description
Event payload	`{ "companyId": 637323, "type": "employee.created", "triggeredBy": "3332883804594373380", "triggeredAt": "2024-12-26T11:29:14.399997", "version": "v2", "data": { "employeeId": "3332883894235038486" } }
API endpoint	Read company employee fields by employee ID.
API call	API call to retrieve default employee data: `POST https://api.hibob.com/v1/people/3332883894235038486 { "humanReadable": "" }` API call to retrieve specific fields: `POST https://api.hibob.com/v1/people/3332883894235038486 "fields": [ "root.id", "root.firstName" ], "humanReadable": "" }`
Permissions	Default fields: Ensure the service user has the following default permissions: People's data > People > About > View selected employees' About sections People's data > People > Basic info > View selected employees' Basic info sections People's data > People > Work > View selected employees' Work sections People's data > People > Work contact details > View selected employees' Work contact details sections Other fields: Grant permissions to the service user for the relevant categories. For example, to fetch the root.id and root.firstName fields, you should grant permission for: People's data > People > Basic info > View selected employees' Basic info sections.

employee.updated

Action	Description
Event payload	{ "companyId": 637323, "type": "employee.updated", "triggeredBy": "3332883804594373380", "triggeredAt": "2024-12-26T11:29:14.399997", "version": "v2", "data": { "employeeId": "3332883894235038486", "fieldUpdates": [ { "root.id", "root.firstName" } ] } }
API endpoint	Read company employee fields by employee ID.
API call	`POST https://api.hibob.com/v1/people/3332883894235038486 "fields": [ "root.id", "root.firstName" ], "humanReadable": "" }`
Permissions	Grant permissions for the specific categories to which the updated fields belong. In this example: People's data > People > Basic info > View selected employees' Basic info sections..
Comments	In Webhooks v1, the payload included both the updated values and the original values for each field. In Webhooks v2, only the current values for changed fields are available. At this time, there is no API option to retrieve historical changes. To track changes over time, you can compare the new value with the previous value stored in your system before applying the update. If you don’t have the previous value stored, you can access the original values of updated fields through the audit trail in Bob’s UI: 1. Open the employee profile. 2. From the top right, click Actions > View audit trail.

table.entry.updated

For table update events, the table name and row identifier appear in the payload. Depending on the table type, the row identifier can be:

effectiveDate- in historical tables.
id- in non-hitorical tables.

Uee the table name in the endpoint URL to retrieve the entries of table and then use the entry identifier to find the row.

Employment table (historical, row-id = effectiveDate )

Action	Description
Event payload	{ "companyId": 636192, "type": "table.entry.updated", "triggeredBy": "3332883804594373380", "triggeredAt": "2025-01-08T13:51:59.935161", "version": "v2", "data": { "employeeId": "3332883904477528858", "tableId": "employment", "effectiveDate": "2025-01-08", "id": null } }
API endpoint	Varies based on the table. See all endpoints in Employee tables.
API call	`GET https://api.hibob.com/v1/people/3332883904477528858/employment` Then Search for the row with effectiveDate = 2025-01-08.
Permissions	Grant permissions for the specific categories to which the table belongs.To learn more, see Employee tables.

Bank accounts table (Non-historical, row-id=id)

Action	Description
Event payload	{ "companyId": 636192, "type": "table.entry.updated", "triggeredBy": "3332883804594373380", "triggeredAt": "2025-01-13T08:50:46.903264", "version": "v2", "data": { "employeeId": "3332883884017713938", "tableId": "bankAccounts", "effectiveDate": null, "id": 6180923 } }
API endpoint	Varies based on the table. See all endpoints in Employee tables.
API call	`GET https://api.hibob.com/v1/people/3332883884017713938/bank-accounts` Then Search for the row with `id=6180923`
Permissions	Grant permissions for the specific categories to which the table belongs.To learn more, see Employee tables.

Time off event example

timeoff.request.requested

Retrieve time-off request details using the entity ID.

Action	Description
Event payload	{ "companyId": 637323, "type": "timeoff.request.requested", "triggeredBy": "3419283646526259215", "triggeredAt": "2024-10-03T09:29:00.831502", "version": "v2", "data": { "timeoffRequestId": 32832853, "employeeId": "3373576791477190995", "getApi": "https://api.hibob.com/v1/timeoff/employees/3373576791477190995/requests/32832853" } }
API endpoint	Get the details of an existing time off request.
API call	Use the getApi property from the payload: GET https://api.hibob.com/v1/timeoff/employees/3373576791477190995/requests/32832853
Permissions	Ensure the service user has the permission: People's Data > Time off > See who's out today > See who's out Additionally, you may need other permissions for private and pending requests. To learn more, see Time off API required permissions.

Task event example

todo.assign

Retrieve the tasks of the employee and then find the relevant task based on the identifier in the payload.

Action	Description
Event payload	{ "companyId": 636192, "type": "todo.assign", "triggeredBy": "3332883804594373380", "triggeredAt": "2025-01-08T12:16:16.034877", "version": "v2", "data": { "requestedForEmployeeId": "3332883884017713938", "workflowId": 2302289, "pivotDate": "2025-01-08", "toDoIds": [ { "id": 32261198 } ] } }
API endpoint	Read tasks of a specific employee
API call	GET https://api.hibob.com/v1/tasks/people/3332883884017713938 Search for task `32261198` in the response.
Permissions	Ensure the service user has the permission: People's Data > Tasks and flow > People's tasks > View and mark selected people's tasks as complete or incomplete. To learn more, see Tasks endpoints.