📘

Migrating to webhooks v2

The 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 retries handling when a webhook fails to send the event.

If you are using V1, please refer to Migrating to webhooks v2.

Webhook v2 event types and payload

Each Bob webhook event corresponds to a specific system action and is triggered by user actions or system changes in Bob. For example, an employee’s details are updated in Bob, or a time-off request is created or modified.

Bob's webhooks v2 events payload have a unified structure that contains metadata about the event, and about the fields that have changed. Additionally, it includes the identifier of the entity that has triggered the event(e.g., employeeId, documentId). To pull the data itself, please use our API.

Event payload data includes:

Retry policy

Bob attempts to deliver a given event to your webhook endpoint for up to 3 days with an exponential backoff. We expect the webhook endpoint's queue to always respond with a 200 (OK) status. repeated failures will trigger retries.

Failure to deliver will be visible on the webhooks page, showing delivery errors. Additionally, email notifications will be sent to Bob Admins and other people selected to get notifications.

Bob webhooks’ retry policy is as follows:

• In case the original notification-sending attempt fails (due to receiving an error response code or exceeding the timeout of 10 seconds), we will retry to send the event in progressively increasing time intervals.
• If it fails in any of these attempts, we will send an email notification as follows:
  • After 1 hour (webhook status: Delivery error)
  • After 24 hours (webhook status: Delivery error)
  • After 48 hours (webhook status: Delivery error)
  • After 72 hours (webhook status: Inactive) - notifying about webhook deactivation
• If there are no successful deliveries on 3 consecutive days, we will deactivate this specific webhook.

📘

Note:

Webhook events are saved for at least two working days. So, if the a webhook becomes deactivated on a non-working day, it will still keep events that occur during the these days, to let your team a chance to fix the issue in the next working day, without data loss. Non-working days include Friday, Saturday, and Sunday.

Email notifications

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..

Disabling policy

Bob attempts to notify you of a misconfigured endpoint by email if the endpoint hasn’t responded with a 2xx HTTP status code for multiple days in a row. The email also states when the endpoint will be automatically disabled.

Webhook listener best practices

Quickly return a 2xx response

Bob server sends a test event to the webhook listener server when establishing a new webhook connection. The test event is sent as a POST request:

1. "Ping test" as a String
2. If previous failed we send a JSON: {"text":"Ping test"}

Ensure your listener endpoint expects this connection message and returns a successful status code (2xx). Also always return the 200 status before any complex logic that could cause a timeout. For example, you must return a 200 response before updating employee details in your external system.

Only listen to event types your integration requires

Configure your webhooks to receive only the types of events your integration requires. Listening for extra events (or all events) puts undue strain on your server, and we don’t recommend it. You can change the events a webhook endpoint receives on the Webhooks settings page in Bob.

Process events efficiently

Set up your system to handle events using an asynchronous queue. This approach helps manage sudden surges in webhook activity without overloading your endpoints. Unlike synchronous processing, asynchronous queues allow your system to handle multiple events smoothly, ensuring better scalability and performance.

Avoid depending on arrival order

Although Bob does attempt to deliver events in the order they are generated, this is not guaranteed. Use the timestamp provided in the event payload to determine the correct order of events.

Ensure events originate from Bob

To increase security while using webhooks, you can whitelist Bob's IPs ↗.

Additionally, validate the webhook signatures included in the Bob-Signature header of each event. These signatures ensure the events come from Bob and not a third party. You can verify them using the webhook’s secret.

Use Bob’s API to retrieve data

The event payload contains only crucial information about the event and the metadata of the changed fields. Use the API to retrieve the data relevant to the update that occurred.

For example, for an employee update event:

{  
 "companyId": 637323,  
 "type": "employee.updated",  
 "triggeredBy": "3332883804594373380",  
 "triggeredAt": "2024-12-26T11:29:14.399997",  
 "data": {  
   "employeeId": "3332883822017713938",  
   "fieldUpdates": [  
     {  
       "id": "root.firstName"  
     }  
   ]  
 }  
}

Use the relevant API call to retrieve values of the fields mentioned in the payload:

POST <https://api.hibob.com/v1/people/3332883822017713938>  
{  
    "showInactive": false,  
    "fields": [  
 		"root.firstName",  
]

For additional examples per event type, see API calls for webhook events .