Why Migrate?
With this new approach, you get:- Faster access to data (get notified when data changes in Kombo)
- Fewer unnecessary syncs (only sync when something has changed)
- More efficient backend usage (reduce load on both your system and ours)
Overview of the Change
Current Approach | New 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 the sync’s schedule (e.g. every 3h) | We notify you when data changes (either after a sync or when we received a webhook) |
Always fetching all data or deltas based on time range | Fetch only if the change affects the models you care about + all data once every 7 days |
Timing of Updates
The speed of data-changed notifications depends on your integration:- Webhook-enabled integrations: Updates typically arrive within 20 seconds (on all plans, webhooks need to be set up)
- Other integrations: Updates arrive based on configured sync frequency (varies by plan and integration)
Migration Steps
1. Implement the data-changed webhook
Set up a webhook endpoint on your side to receivedata-changed
events from Kombo. The webhook’s payload will contain a list of changed_models, such as employees, groups, etc.
See Fetching 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:3. Track fetch state on your end
You should storelast_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
Behavior | Legacy Sync | New Webhook-Based + Sync |
---|---|---|
Data freshness | Scheduled intervals (usually every 3h) | Varies by integration (if webhook are supported & enabled) |
Sync triggers | Always run | Run only when data actually changed |
Volume of requests | Higher, predictable | Lower, event-driven |
Implementation | Based on sync-finished or cron | data-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
- Set up the data-changed webhook handler
- Update your sync logic to be event-driven
- Test the flow in your dev environment
- Remove or reduce interval-based syncs once confident
- Reach out for help if needed