Planned Changes to the API

2025.06.26 - Webhooks Enhancements

We're enhancing our webhooks functionality with several key improvements:

Webhooks enabled by default for all companies — no need to contact support.
Support for delete operations in addition to create and update.
A new real-time event-based framework that allows us to expand coverage in the future, including custom fields and other areas of the product.
Field-specific notifications that only send data about the fields you're monitoring rather than the entire data tables the fields belong to.
Enhanced payloads with two new fields:
- action — indicates whether the employee was created, updated, or deleted
- timestamp — ISO 8601 timestamp of when the change occurred
Improved reliability through comprehensive bug fixes.
Updated documentation with clearer explanations of webhook behavior.

All existing webhooks will continue to work without any changes required. No action is needed from customers or partners.

2025.06.26 - Webhook Scheduling and Rate Limiting Features Being Removed

As part of our webhooks enhancements, we're transitioning from a cron-based system to a real-time event-driven architecture. With this transition, webhook scheduling and rate limiting features are being removed from the user interface as they are no longer needed for the real-time delivery system.

If your current webhook configuration uses scheduling or rate limiting features, your webhooks will automatically transition to real-time delivery with no action required.

2025.06.26 - Webhook Fields Being Removed

As part of our webhooks enhancements, we're removing a number of webhook fields. Some of these fields no longer exist in our database, while others have extremely low usage (some fields used by only 1-3 customers). We will reach out directly to impacted customers with specific details about which fields are being removed and alternative ways to access this data through our public API.

If you don't hear from us, your webhooks are not affected and no action is needed.

2025.04.14 – User API Key Deprecation and OAuth 2.0 Transition

We're phasing out the legacy User API Key login flow, which uses the oidcLogin endpoint to exchange an OpenID Connect id_token for a BambooHR-specific API key. This custom login mechanism is being replaced by standard OAuth 2.0 access tokens, which offer stronger security, clearer permission scopes, and broader industry support.

As part of this transition, any application that used oidcLogin on or before April 14, 2025, may continue using it temporarily—but only if the legacy.login scope is included in the scope field of its token.php request. This scope must be added by July 31, 2025. It ensures the system can properly authorize the request and present the appropriate consent to users. Requests missing this scope after the deadline will be rejected.

✅ Example:
https://acme.bamboohr.com/authorize.php?request=authorize&state=new&response_type=code&scope=openid+legacy.login&client_id=123456789&redirect_uri=https://app.acme.com/oauth/callback

In this example, acme is the company’s BambooHR subdomain. Scopes are separated by + in the URL. Be sure to include legacy.login if your app is still using the oidcLogin endpoint.

Applications created after April 14, 2025, will not be permitted to use oidcLogin at all. These apps must use OAuth 2.0 from the start.

We strongly recommend that all developers begin migrating away from the User API Key flow and adopt OAuth 2.0 as soon as possible. OAuth is now the recommended and fully supported method for authenticating with the BambooHR API.