Please be aware that this page covers downstream webhooks. These are webhooks
that Kombo sends to your system for events like new integrations or finished
syncs. If you try to understand webhooks that Kombo receives from the
connected ATS/HRIS such as Personio or Recruitee, check out this
page.
Enable Webhooks
You can configure your Kombo webhooks in the dashboard directly in the webhooks tab. After creating the first webhook, a random webhook secret will be generated and shown. You can learn how to use it in Validate the data.
Available webhooks
Data changed
We send adata-changed
webhook every time data changes in Kombo. This includes
changes from regular syncs as well as updates from upstream webhooks.
Read more about the modern fetching approach here.
We trigger this webhook, when we receive a change. To speed up delivery of
changes to Kombo, ensure that upstream webhooks are enabled for the
integration. If upstream webhooks are not enabled or not supported,
notifications are sent after the next scheduled sync (latency equals the sync
frequency).
updated_after
filter.
This webhook is useful to fetch data from Kombo into your system. Read more
here.
We will only ever send you a data-changed
webhook if there are changes to the data.
data-changed
data-changed
with a 30-second window by default. This means
that you will at most receive one data-changed
webhook every 30 seconds.
When the webhook is triggered for the first time, we send it out immediately.
After that, we will wait 30 seconds, during which we will collect all events and
send them as a single webhook, thereby starting another 30-second cooldown
window. We do not wait for syncs to finish before sending out the webhook;
instead, we may send you multiple webhooks during a single sync to ensure you
receive changes as soon as possible.
Sync finished
Thesync-finished
webhook is sent every time a sync finishes, regardless of
the sync state. Possible values for sync_state
are:
SUCCEEDED
The sync finished successfully.FAILED
There was a critical error during the sync and the sync did not finish.PARTIALLY_FAILED
There was a non-critical error that needs your attention. Please check the logs for actionable error messages or contact us for support.AUTHENTICATION_FAILED
The authentication of the connection is incorrect. Please check the Kombo dashboard for further steps.
The
sync_started_at
field represents when Kombo started syncing data from
the connected system, not when you should start fetching from Kombo. Do not
use this field as your updated_after
parameter when fetching data.
Otherwise, you might risk missing data that was created/updated via webhooks
before the sync started.sync-finished
Integration created
Theintegration-created
webhook is sent for every integration that is created.
Please react to this webhook event by adding the integration to your database
or by performing any other business logic that is required when an integration is
created.
integration-created
Integration deleted
Theintegration-deleted
webhook is sent when an integration is deleted.
Please react to this webhook event by removing the integration from your database
or by performing any other business logic that is required when an integration is
deleted.
integration-deleted
Connection flow failed
Theconnection-flow-failed
webhook is sent whenever an error occurs during the
connection flow. These errors could, for example, originate from a user entering
incorrect credentials or from a mismatch between the required and supplied API
permissions.
This is not an alert-type webhook, but should instead be used to collect data
and get insights into user behavior. The connection flow can still be
successfully completed after this webhook is sent.
You can check whether the connection flow ended successfully by following the
link under log_url
. Additionally, the log will display the exact errors your
customer ran into, which you can use to provide support if needed.
connection-flow-failed
Assessment order received
Theassessment:order-received
webhook is sent every time an assessment is
ordered for a candidate from within an end-customer’s tool.
assessment:order-received
Integration state changed
Theintegration-state-changed
webhook is sent when the status of the
integration changes. Use this to detect stale credentials and to reconnect your
customer.
Possible values for the "state"
key include:
ACTIVE
The integration is active and working.INVALID
The connection requires reconnection in order to work again.INACTIVE
Upon your request, Kombo support can mark the integration as inactive.
integration-state-changed
Validate the data
Anyone could post data to your webhook URL. That’s why we’re signing each request with a secret specific to your Kombo account. This secret is called the Kombo Webhook Secret and you can find it on the Kombo dashboard. Each valid webhookPOST
request from us will include the X-Kombo-Signature
header. To validate it, carefully follow these steps:
- Decode the
X-Kombo-Signature
header frombase64url
encoding (without padding) to raw bytes. - Compute the HMAC-SHA256 over the raw JSON request body (Kombo encodes this using two-space indentation) with your Kombo Webhook Secret as raw bytes.
- Compare the decoded signature bytes to the computed HMAC bytes using a
constant-time comparison function (like Node.js’s
timingSafeEqual
) to protect against timing attacks.
If you’re stuck trying to get the signatures to match, please verify that:
- You’re using the Webhook Secret of the correct Kombo environment (e.g., production or development).
- You’re using the raw JSON request body. If your framework already parses
the JSON body for you, make sure to re-encode it with two-space indentation
(e.g.,
JSON.stringify(body, null, 2)
in JavaScript). - You’re decoding the signature header from
base64url
(not standardbase64
) and comparing raw bytes (not re-encoding the computed HMAC for string comparison).