Server-to-partner webhooks fired when a US pay cycle is paid.
Partner OAuth integrations only
The Background Checks API is for approved HiBob Marketplace partners with Developer Portal access and OAuth credentials. Service users are not supported for this integration.
Bob customers building integrations for their own company should use Service users and the general Hiring API, not this partner contract.
Before you begin
- Read Integrate with Retirement Partners API to learn how to use this API.
- Verify the
bob-signatureheader on every webhook before processing. See How does Bob calculate the signature.
Persist the webhook, then pull pay-cycle data. Do not treat the payload as a full paycheck dump.
Retirement Partners API webhooks
| Webhook | Identifier | When triggered | Next step |
|---|---|---|---|
| Pay cycle paid | payroll.paycycle.paid | A US pay cycle is completed and available for fetching | Use data.payCycleId to fetch cycle metadata and paychecks |
Required permissions and scopes
Receiving the webhook does not replace API scopes. After you get payCycleId, your OAuth app still needs:
| Name | Scope | Description |
|---|---|---|
| Payroll Hub > Partner integration > Fetch pay cycle metadata, paystub information, and payroll-related employee data | payrollhub.payroll:read | Fetch the paid cycle and its paychecks. |