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 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 | `{ |
API endpoint | |
API call | API call to retrieve default employee data:\
API call to retrieve specific fields:\
|
Permissions |
|
employee.updated
Action | Description |
---|---|
Event payload | {
|
API endpoint | |
API call |
|
Permissions | Grant permissions for the specific categories to which the updated fields belong. In this example: |
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:
|
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 | {
|
API endpoint | Varies based on the table. See all endpoints in Employee tables. |
API call |
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 | {
|
API endpoint | Varies based on the table. See all endpoints in Employee tables. |
API call |
Then Search for the row with |
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 | {
|
API endpoint | |
API call | Use the getApi property from the payload: |
Permissions | Ensure the service user has the permission: |
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 | {
|
API endpoint | |
API call | GET https://api.hibob.com/v1/tasks/people/3332883884017713938 |
Permissions | Ensure the service user has the permission: |