Upstream webhooks
Kombo can subscribe to webhooks of the systems that your customers connect. We call this feature upstream webhooks. This document explains how they work and how you can leverage them.
Please be aware that this page covers upstream webhooks. These are webhooks that Kombo receives from the connected ATS/HRIS such as Personio or Recruitee. If you try to understand webhooks that Kombo sends to your system for new integrations or finished syncs, check out this page.
Concept
Kombo can subscribe to webhooks of the systems that your customers connect. We call this feature upstream webhooks. The goal of this system is to enable you to receive data in real-time without waiting for a normal sync to complete.
Setup
Upstream webhooks are available for a limited set of integrations as not all integrations support them yet. You can check out the coverage grid to understand which integrations support this feature.
The feature is by default on your environment but you also need to enable the feature in the scope config to use it.
Toggle this setting in the scope config on the dashboard.
This is what the end-customer will see in the connection flow.
When this setting is enabled, Kombo will call the connected system’s API to subscribe to the webhook. You can manage the webhook subscription in the Kombo dashboard as well.
End-Customer Experience
For most integrations, the end-customer only needs to grant a permission to the credentials to allow us to subscribe to webhooks.
Kombo will also diligently only subscribe to webhook event types that are compliant with the scope config. For example, if you disable candidates and only care about jobs, we will not subscribe to any candidate events.
Implementation Guide
This feature enables you to sync data in real-time to wait for a normal Kombo sync to complete. Kombo enables this by subscribing to the webhooks of the ATS/HRIS and then informing you about a handled event.
Set up the downstream event in the webhook config in the Kombo dashboard.
Reacting to the downstream event can be handled in the exact same way you would handle
sync-finished events. After receiving the event, you can call the Kombo API
with the updated_after filter to only get entries that have changed since your
last sync with Kombo.
You can usually expect to receive events from the connected system within 10-20 seconds. Most systems take a few seconds before they send the webhook to Kombo.
Kombo will retry the request to your system for up to 5 times with exponential backoff.
Supported data models
We support upstream Webhooks for the following use cases:
ATS:
- new candidate
- candidate deleted
- job updated
- job unpublished
- job published
HRIS:
- employee created
- employee updated
- employee deleted
- absence period created
- absence period updated
The remote-event-received webhook notifies you when Kombo received an update from the remote system. After receiving this webhook, run a sync with Kombo similarly to how you would after receiving the sync finished webhook.
Upstream webhooks in combination with syncs
Regardless of using upstream webhooks, we strongly recommend that you continue to rely on the sync finished webhook for regular syncs. Upstream webhooks are designed to complement, not replace, syncs by delivering real-time data for supported events and models. For data models, integrations, or events that don’t support webhooks, listening to the sync finished webhook will continue to be essential.
Scenario
Previously, fast sync frequencies (e.g., every 10 minutes) have been a way to keep data as up-to-date as possible with changes in your customer’s system. However, with an upstream webhook implementation, you are able to achieve much more precise syncs, by reacting to actual changes in your customer’s system.
Upstream webhooks allow you to receive specific changes as they happen, delivering near real-time updates while otherwise keeping a 3-hour sync frequency. This approach lets you get customer data faster without the downside of high system load and unnescessary API requests. For any integration that doesn’t yet support upstream webhooks, high-frequency syncs are still available, but upstream webhooks offer a more efficient and responsive solution.
As you continue to use the sync finished webhook, you don’t need to make any changes to your current integration—just add the support for upstream webhooks to your system for a seamless transition to real-time data access.
That way, you can keep fast sync frequencies for the integrations that don’t have webhooks enabled while switching over to 3-hour sync frequencies + upstream webhooks for the integrations that do.
Troubleshooting
Check out the logs in the Kombo dashboard to see every webhook event that we receive. The downstream request will also be logged there with any warnings or errors that we encountered while processing or forwarding the event.
