Starting January 21, 2025, Bob Webhooks v2 will be open for use. This guide will give you an overview of the changes you need to make to switch from version 1 (v1) to version 2 (v2).

🚧

Note:

Webhooks v2 will eventually replace Webhooks v1. Please consider migration as soon as convenient.

About webhooks v2

Bob Webhooks v2 adds reliability and stability by reducing the data sent on the payload, ensuring the events will be sent in the right order, and better handling of retries when a webhook fails to send the event.

Migration notes

1. For added reliability and stability, we recommend using Webhooks V2.
   Webhooks V2 introduces improvements like reduced payload size, better retry mechanisms, and more secure data delivery.
2. No immediate action is required for existing Webhooks V1.
   For now, Webhooks v2 and v1 will continue to run in parallel, and you do not need to make any changes.
3. We’ve made some structure changes to the payload format.
   Webhooks V2 payloads focus on metadata, and detailed data can be retrieved using Bob's API.
4. Revised delivery mechanism and email notifications.
   The retry mechanism now includes email notifications for delivery issues. To address any issues proactively, set up the appropriate people to receive these notifications.

Migration timeline

Starting April 1, 2025 you will no longer be able to create new V1 webhooks.

• Starting January 21, 2025, you can start creating v2 webhooks in Bob's UI.
• You can still create new v1 webhooks from Bob’s UI until April 1, 2025, but we recommend reviewing the documentation and considering using v2 for your existing and future developments.
• Existing webhooks v1 will continue to run in parallel to v2 after April 1, 2025, but users will be able to create only new webhooks v2.
• We will provide advance notice before any future deprecation of v1 webhooks functionality, ensuring a smooth transition.

Changes in Webhooks V2

Structure changes

The old payload had a structure similar to the responses you get from our API. The payload now contains only crucial information about the event and the metadata of the changed fields.

The webhook payload now has a unified structure for all events, including the event and data fields.

New fields in V2

Each event payload now includes the following fields:

• version - the webhook version (v2).
• triggeredBy - ID of the employee that triggered the event or ‘system’.
• triggeredAt - timestamp when the event occurred.

Revised fields in V2

The fields that are relevant to the object being changed will now appear in the data section

• Field IDs - All field IDs are returned using the “id” notation rather than the “path” notation. This aligns with other endpoints returning metadata and can be used seamlessly when querying data using the API.
  • V1 “path” notation: “/root/id”
  • V2 “id” notation: “root.id”
• type - formerly called 'type' or 'event' (for time off events) - contains the event type based on Bob’s supported events.
• data section - contains the actual data and differs for each event type. In V1, it used to exist for update events, but now contains different fields, so pay attention to the differences. To learn more about each event, see Payload structure.

Fields that have been moved or added

• Data section: All fields containing data about the entity being changed and previously at the payload's top level now appear in the data section.
• Metadata only: The payload contains only metadata about the changed fields (the field IDs) and the ID of the updated entity (e.g. employeeId, documentId). To pull the data itself, please use our API.
• The changedBy property: Used to be an object with all the details about the employee who made the change. Now, it is renamed to triggeredBy and contains only the employee ID.
• Table entry created/updated events: The payload now includes the tableId, and an identifier of the entry, which can be either entryId or effectiveDate. To pull the table entry’s data, please use our API.

Webhooks v2 payload format

Note that there are significant differences in webhooks v2’s payload, so please review it closely.

Following is an example of an employee.updated event and how the payload looks in V2 vs V1:

{  
  "companyId": 636192,  
  "type": "employee.updated",  
  "triggeredBy": "3332883804594373380",  
  "triggeredAt": "2024-12-30T12:56:18.955603",  
  "version": "v2",  
  "data": {  
    "employeeId": "3498867108266115473",  
    "fieldUpdatesIds": [  
      {  
        "id": "root.surname"  
      },  
      {  
        "id": "root.displayName"  
      }  
    ]  
  }  
}

{
  "companyId": 636192,
  "employee": {
    "id": "3498867108266115473",
    "companyId": 636192,
    "firstName": "Joe",
    "surname": "Doe",
    "email": "[email protected]",
    "displayName": "Joe Doe",
    "site": "New York (Demo)",
    "siteId": 2510068,
    "impersonatorInfo": null
  },
  "changedBy": {
    "id": "3332883804594373380",
    "companyId": 636192,
    "firstName": "Sandra",
    "surname": "Miller",
    "email": "[email protected]",
    "displayName": "Sandra Miller",
    "site": "London (Demo)",
    "siteId": 2510067,
    "impersonatorInfo": null
  },
  "type": "employee.updated",
  "data": {
    "fieldUpdates": [
      {
        "path": "/root/surname",
        "originalValue": "Doe",
        "newValue": "Doey"
      },
      {
        "path": "/root/displayName",
        "originalValue": "Joe Doe",
        "newValue": "Joe Doey"
      }
    ]
  },
  "operationType": "Update",
  "previous": null,
  "creationDate": "2024-12-30T12:56:18.955603"
}

Revised delivery mechanism (retry policy)

The retry mechanism for webhooks has been enhanced to provide a more reliable delivery mechanism.

When a webhook fails, the server notifies Bob Admins via email, letting them know they should fix the problem on the webhook listener side and providing suggested resolutions whenever possible. Additionally, you can configure specific users to be notified of delivery issues.

Refer to the Webhooks Retry Policy documentation for full details on the new retry mechanism and deactivation process.

Next Steps

• Review your existing webhooks.
• Try out the v2 webhooks. For further details, see Getting started with webhooks.
• Review webhooks v2 events.
• Adjust the code to process the new payload to ensure compliance with the updated policy and best practices.
• Adjustments include using the Public API to retrieve data. Explore some API calls examples of how to use the API to retrieve the event data fields.

FAQ

Will my existing v1 webhooks still work?
Yes. No immediate action is required for existing Webhooks V1. They will continue functioning as usual for now, and you do not need to make any changes.

Remember, starting on April 1, 2025, you will not be able to create webhooks v1 from Bob's UI, so we recommend that you transition as soon as possible.

Do we have to migrate to Webhooks v2?
We will eventually deprecate Webhooks V1, so we encourage you to migrate to v2. Bob Webhooks v2 adds reliability and stability by reducing the data sent on the payload, ensuring the events will be sent in the right order, and better handling of retries when a webhook fails to send an event.

Can I still create v1 webhooks in Bob?
Yes. When creating webhooks from Bob's UI, the system defaults to V2. However, you can still select V1.

Remember, starting on April 1, 2025, you will not be able to create webhooks V1 from Bob's UI, so we recommend that you transition as soon as possible.

What are the main differences between v1 and v2?
The main differences include:

1. Enhanced retry mechanism with email alerts when a webhook listener is not responding.
2. The payload was reduced to include only metadata about the event.
3. You must now use the API to pull the data from Bob, making the integration more secure.