Webhook Use Case

Use our webhooks to be notified about finished syncs. This allows you to fetch any changes that occurred during a sync. This allows you to keep your database up to date without scheduling/polling.
Easily test webhooks with Webhook.site.

Enable Webhooks

You can configure your Kombo webhooks in the dashboard by clicking on the "Webhooks" tab in the sidebar. After creating the first webhook, a random webhook secret will be generated and shown. Learn in validate the data how to use it.

Data Schema

Our webhooks follow this schema:

{
  "id": "5gjAtURLPbnTiwgkaBfiA3WJ",
  "type": "sync-finished",
  "data": {
    "sync_id": "EY2KfFEZ5Vc2FVfVUQFpRduM",
    "sync_state": "SUCCEEDED",
    "sync_started_at": "2022-11-02T10:50:10.242Z",
    "sync_ended_at": "2022-11-02T10:50:14.751Z",
    "sync_duration_seconds": 14.509,
    "integration_id": "personio:hris-dev",
    "integration_tool": "personio",
    "integration_category": "HRIS"
  }
}

React correctly

Kombo will send you a webhook for every sync that either succeeded or failed (during authentication or processing). You will only be able to pull data from an integration that finished at least one successful sync. Therefore, you should validate the sync_state.

Possible values that you can get as a sync_state from the webhook are:

• SUCCEEDED -> everything right; you can request data
• PARTIALLY_FAILED -> there were minor problems or inconsistencies in the sync, you can still work with the data
• FAILED -> there were major inconsistencies in the sync. Please review the sync first.
• AUTHENTICATION_FAILED -> we could not make requests against the API. This potentially indicates that the credentials expired or the connected API had downtime.

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. The secret is called Kombo Webhook Secret and will be sent to you when we activate Webhooks for you.

Each valid webhook POST from us will include the X-Kombo-Signature header. Validate it by using HMAC-SHA256 to sign the request body with the Kombo Webhook Secret and then digest it with base64url.

In Node.js, it could, for example, look like this:

import { createHmac } from 'node:crypto'

const signatureHeader = req.headers['x-kombo-signature']

// Get the raw UTF-8-encoded string body because this was used for signing
const body = request.body

const signature = createHmac('sha256', signatureSecret)
  .update(body, 'utf8')
  .digest('base64url')

const isValidRequest = signature === signatureHeader