Kombo now offers a webhook-first method to stay updated with HRIS data changes (e.g., employees, groups, etc.), enabling faster and more efficient access to information. This guide walks you through how to migrate from the traditional sync-based approach to listening for changes with the new data-changed webhook.

​
Why Migrate?

With this new approach, you get:
  • Faster access to data (get notified immediately when data changes)
  • Fewer unnecessary syncs (only sync when something has changed)
  • More efficient backend usage (reduce load on both your system and ours)
There is no deprecation date for the legacy sync system yet, but all future improvements will be built around this approach. Therefore, we strongly encourage switching over as soon as possible.

​
Overview of the Change

Current ApproachNew Approach
Your backend fetches data based on our periodic sync-finished webhook (no matter if something changed)Kombo notifies you of data changes via a webhook, and you fetch data only when needed
This happens on a schedule (e.g. every 5 min)We notify you as soon as changes happen (within seconds)
Always fetching all data or deltas based on time rangeFetch only if the change affects the models you care about + all data once every 7 days
In other words: you no longer need to fetch blindly — we tell you when something changed.

​
Migration Steps

​
1. Implement the data-changed webhook

Set up a webhook endpoint on your side to receive data-changed events from Kombo. The webhook’s payload will contain a list of changed_models, such as employees, groups, etc. See Syncing Data for a full example and implementation tips. Simplified approach To make things simple, you can, whenever you receive a new data-changed webhook, pull the models you’re interested in, independent of the models we’re telling you changed. Recommended approach You can also listen to the data models we’re telling you that changed and pull data based on the models. For that please look into the list of models that can appear.

​
2. Adjust your fetching logic

Previously, you might have done something like: 
// Always fetch employees
await fetchEmployees()
Now, switch to: 
const employeesChanged = !!body.data.changed_models.find(
  entry => entry.name === 'hris_employees',
)

// Fetch data only when data-changed webhook indicates a change
if (employeesChanged) {
  await fetchEmployeesOnlyIfWebhookSaysSo()
}
Make sure to still pass the lastFetchStartDate as a parameter to avoid duplicate records.

​
3. Track fetch state on your end

You should store last_fetched_from_kombo_at in your database and update it after each successful fetch. Use the Kombo sync start time for this value (not the end time). This ensures you don’t fetch overlapping data and that you fetch all relevant data again with the next fetch.

​
4. Test in Development

We suggest you test this flow in your development environment first. You can simulate data-changed webhook events from Kombo’s side or trigger a real change via your connected sandbox HRIS account. If you’re running locally, you can use a tool like ngrok to receive webhook events on your machine by exposing your local server to the internet.

​
Expected Behavior Differences

BehaviorLegacy SyncNew Webhook-Based
Data freshnessScheduled intervals (e.g. max every 5-10 min, but usually every 3h)Near real-time
Sync triggersAlways runRun only when data actually changed
Volume of requestsHigher, predictableLower, event-driven
ImplementationBased on sync-finished or crondata-changed and cron (weekly)

​
FAQs

Is this a breaking change? No - this is not a breaking change. However, the new data-changed approach is significantly more efficient, provides faster data updates, and our strongly-recommended path forward. Can I keep fetching using sync-finished webhook? We strongly recommend implementing the new data-changed webhook and data fetching approach. While our legacy sync-finished webhook will remain active for now, all future efforts to increase efficiency, provide faster data updates, and introduce other improvements will be focused on the data-changed webhook. What if a webhook fails? Failing webhooks should not occur and our data-changed webhook is designed to be resilient. If you want to guarantee no data changes are missed, you can perform a periodic data refresh and fetch data from all Kombo’s endpoints you care about, in addition to reacting to the data-changed webhook. In most cases, a weekly refresh every 7 days is ideal. What data models are supported? Any model listed here is eligible, including employees, groups, etc.

​
Support

If you have any questions or want to discuss your migration, just ping us in our Slack or Microsoft Teams channel. We’re here to help you transition smoothly.

​
Next Steps

  1. Set up the data-changed webhook handler
  2. Update your sync logic to be event-driven
  3. Test the flow in your dev environment
  4. Remove or reduce interval-based syncs once confident
  5. Reach out for help if needed