Getting started with partner webhooks

Bob webhooks allow you to subscribe to system events and receive programmatic notifications about changes as they occur.

Bob customers can define webhooks manually in Bob, and listen to events. However, partners using OAuth use a slightly different webhooks delivery and retry mechanism, which is explained in this article.

To learn more about using Bob webhooks in general, see:

• Webhook payload structure
• How to develop a webhook listener
• How Bob calculates a signature
• Testing webhooks

Partner webhooks

Partner webhooks enable your app to automatically receive event notifications from Bob whenever a change occurs in a customer's account.

When a customer installs your app via OAuth, Bob automatically sets up webhooks behind the scenes. These webhooks are invisible to the customer and are fully managed by your integration. No manual setup is required.

As a partner, your app will need to provide HiBob with a single webhook listener URL that processes all incoming events from all your customers. You will need to ensure that each event received is mapped to the correct client.

When a webhook listener fails, this will affect all your customers. Ensure you have a solid recovery implementation in place to handle failures, as explained in this article.

Webhook retry behavior

When Bob sends an event to your webhook listener and receives an error (e.g., a 4xx or 5xx response), we will automatically retry the request using a short exponential backoff:

If your endpoint does not respond successfully within this ~3-hour window, the webhook delivery for that specific event will stop.

👍

Your endpoint must respond within 10 seconds with a 2xx status code to be considered successful.

Webhook unavailability detection

If Bob detects that your webhook is consistently failing across most requests, we will notify you so you can take action.

When we notify you

Bob evaluates the delivery success rate of your webhook every 30 minutes. If 80% or more of events are failing, we consider your webhook to be unavailable.

We’ll send you notifications based on how long the issue persists:

👍

When a webhook is deactivated, no events will be delivered until the issue is resolved and your integration reactivates the webhook setup

How notifications are delivered

Notifications are sent to your system via your configured queue (e.g., SQS). They contain structured information about:

• The impacted app
• The partner webhook ID
• The failure timestamp
• The severity (warning or deactivation)
• Recommended next steps

What you should do

Listen for failure notifications

It’s your responsibility to consume the notifications and:

• Monitor the queue where Bob sends partner notifications.
• Handle both warning and deactivation messages.
• Alert your engineering or DevOps teams
• Restore your webhook availability
• Re-enable your webhook configuration once the issue is resolved.

Set up your listener correctly

• Ensure your webhook endpoint responds with a 2xx HTTP status code.
• Avoid long processing in the webhook itself. Respond quickly, then process asynchronously.
• Implement idempotency to handle retries.

Monitor delivery health

• Track response times and error rates on your side.
• Alert internally when your endpoint experiences issues.

Testing and validation

During development, we recommend:

• Using webhook testing tools (e.g., webhook.site) to inspect payloads
• Validating your listener returns a 200 OK response to Bob
• Simulating failure conditions to test notification handling and reactivation flows

Related articles

• How Bob signs webhook requests
• Test your webhook endpoint
• Quick start guide for adding apps