Learn how to subscribe to events in Bob and be notified whenever a change occurs.
Bob provides the ability to subscribe to events that occur in the system. You should provide an endpoint URL, which will be called whenever an event occurs. Each event will send the information about the event in the event's payload.
Overview
Bob webhooks allow you to subscribe to system events and receive programmatic notifications about changes as they occur. When adding a webhook, you should provide a webhook URL, which you will use whenever an event occurs. Each event will send the information about the event in the event's payload.
When one of those events is triggered (for example, a new employee is added), Bob will send this notification as an HTTP POST request, with a JSON body, to the endpoint you specify. If you’re new to webhooks, read this guide to learn more.
Start developing
To add new webhooks and start receiving events, follow the steps in Working with webhooks.
Manage webhooks in Bob's UI
Once you add webhooks in Bob, they are listed on the Webhooks page. From there, you can edit their description, refresh the token, test the webhook, activate or deactivate it, and view the log history.
To manage webhooks in Bob, see Manage Webhooks ↗.
Webhook listener best practices
Follow these best practices when you develop your event listener Webhook to catch the events:
Don't rely on the event's payload:
When you implement the event listener on your side, consider that Bob Events sends some of the data related to the event as the event's payload. As a best practice, we advise using the Webhooks' event payload as a notification only and then making an API call to retrieve all the necessary data. To learn more, see Getting Started with the Bob API.
Handle an 'incoming events' queue:
Bob supports performing bulk changes that can be generated by either the client or a system update. If a bulk change is made, the server may receive multiple concurrent events indicating the changes that took place. To manage multiple concurrent events, we recommend creating a queue on the listener end. This queue will buffer incoming events, allowing the server to process them appropriately. This approach ensures that bulk changes are captured correctly and that your listener responds appropriately while maintaining the connection.
Quickly return a 200 response to validate your connection and avoid timeouts:
Bob server sends a test event to the webhook listener server when establishing a new webhook connection. 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.
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.