API calls examples to retrieve the data relevant to webhook events
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 exampe
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", "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", "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.. |
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/employmentThen 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-accountsThen 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", "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. |