Webhooks and data fetching

Overview

AI Apply is asynchronous by design. Parsing a job posting and submitting an application both run in the background. AI Apply provides two webhooks so that you do not need to poll for results:

The data-changed webhook notifies you that job postings in your environment changed. Fetch the changes with the updated_after filter to keep postings and application forms current.
The application updated webhook reports the outcome of a single application and includes the application in its payload.

First time implementing Kombo webhooks?View our general Webhooks guide for delivery, signature validation, retries, and other behavior shared by every Kombo webhook.

Data-changed webhook

Strategy

Perform one full fetch of your job postings, then fetch only the changes whenever the data-changed webhook arrives. The webhook signals that data changed. The updated_after filter limits the response to changes since your previous fetch.

The data-changed webhook

Kombo sends ai-apply-data-changed when one or more job postings in your environment changed in a customer-facing field: availability, archival, URL, job code, career site, or the application form. This includes a posting finishing parsing, a bulk import archiving postings, and a re-parse producing a new application form. The payload names the changed model, not the changed records. The webhook is a notification, not a data delivery. Fetch the relevant endpoint after receiving it.

{
  "id": "2Cv6VeT4efBfzvQRudprNx5z",
  "type": "ai-apply-data-changed",
  "data": {
    "environment_id": "my-prod",
    "changed_models": [{ "name": "job_postings" }]
  }
}

The webhook is debounced with a 30-second window. The first change is delivered immediately. Changes within the following 30 seconds are batched into a single webhook, which starts the next window. You receive at most one webhook per 30 seconds, and none while no data changes.

changed_models covers job postings only. Application outcomes are not delivered through this webhook. They are delivered through the application updated webhook, which includes the application itself, so no follow-up fetch is required.

Configuring the webhook

Create the webhook in the Kombo Dashboard under Configuration, Webhooks. Select the type AI Apply: Data changed, enter a label, and enter the URL Kombo should call.

Creating the AI Apply data-changed
webhook

Every webhook is signed with the signing secret shown on the same page. See Validate the data for how to verify the signature.

Fetching changes with updated_after

Both job posting endpoints accept an updated_after query parameter in ISO 8601 format. The response includes every posting whose updated_at is equal to or later than the given timestamp. Delta fetches are especially important for GET Job Postings Forms. Application forms are large, so the endpoint returns at most five postings per page, and fetching an entire catalogue requires many requests. A delta after a webhook typically fits in one. Which endpoint to sync depends on how you obtain application forms:

If you inquire per posting when a candidate applies, sync GET Job Postings. It provides posting metadata and availability without the form.
If you hold forms locally, sync GET Job Postings Forms. Each changed posting is returned with its current application form and submission token, so a delta fetch also delivers the replacement for any stored form.

Both guides document the response shapes in detail.

Keeping track of the timestamp

Use the start time of your previous fetch as the updated_after checkpoint, not the latest updated_at value in its results. This is the same method used for the Unified API.

Record the current UTC time immediately before requesting the first page.
Follow next until it is null, keeping every filter unchanged between pages.
Once every page has succeeded, store the recorded start time as the new checkpoint.
On the next fetch, pass that checkpoint as updated_after.
Upsert results by posting id.

Recording the start time ensures that a posting changed while you were paging is included in the next delta. Advancing the checkpoint only after all pages succeed ensures that a failed fetch is repeated in full and no change is skipped. Both properties, together with the inclusive comparison, mean that the same posting can be returned more than once. Upserting by posting id handles this without additional logic.

Job Posting Updated Webhook

The ai-apply-job-posting-status-updated webhook is deprecated. Use the data-changed webhook together with updated_after instead. It still fires for existing setups, but do not build on it.

Lifecycle

Status	Emits webhook?	Description
`PENDING`	❌	Parsing is queued/processing
`APPLYABLE`	✅	Kombo has successfully parsed the job posting. You can submit applications
`UNAVAILABLE`	✅	Parsing the job posting failed
`ARCHIVED`	✅	The job was taken offline or manually archived

If a parse attempt fails but a previous successful revision still exists, the posting remains APPLYABLE.

Payload

The payload matches the job posting schema you receive from the get job posting endpoint. Examples

A job posting was successfully parsed.

{
  "id": "2Cv6VeT4efBfzvQRudprNx5z",
  "type": "ai-apply-job-posting-status-updated",
  "data": {
    "id": "9QGNv3B98kL3hyELE1qsZ86s",
    "career_site": { "id": "Chc4dua5asAQ48KUERDVF1bs", "label": "Acme" },
    "url": "https://careers.acme.com/jobs/fullstack-engineer-ai-infra-14102",
    "job_code": "ACME_13",
    "created_at": "2025-01-01T00:00:00.000Z",
    "updated_at": "2025-03-02T23:12:32.000Z",
    "archived_at": null,
    "archived_reason": null,
    "availability": "APPLYABLE"
  }
}

A job posting failed to parse.

{
  "id": "2Cv6VeT4efBfzvQRudprNx5z",
  "type": "ai-apply-job-posting-status-updated",
  "data": {
    "id": "9QGNv3B98kL3hyELE1qsZ86s",
    "career_site": { "id": "Chc4dua5asAQ48KUERDVF1bs", "label": "Acme" },
    "url": "https://careers.acme.com/jobs/fullstack-engineer-ai-infra-14102",
    "job_code": "ACME_13",
    "created_at": "2025-01-01T00:00:00.000Z",
    "updated_at": "2025-03-02T23:12:32.000Z",
    "archived_at": null,
    "archived_reason": null,
    "availability": "UNAVAILABLE"
  }
}

A job posting was taken offline.

{
  "id": "2Cv6VeT4efBfzvQRudprNx5z",
  "type": "ai-apply-job-posting-status-updated",
  "data": {
    "id": "9QGNv3B98kL3hyELE1qsZ86s",
    "career_site": { "id": "Chc4dua5asAQ48KUERDVF1bs", "label": "Acme" },
    "url": "https://careers.acme.com/jobs/fullstack-engineer-ai-infra-14102",
    "job_code": "ACME_13",
    "created_at": "2025-01-01T00:00:00.000Z",
    "updated_at": "2025-03-02T23:12:32.000Z",
    "archived_at": "2025-03-10T08:15:00.000Z",
    "archived_reason": "JOB_POSTING_TAKEN_OFFLINE",
    "availability": "ARCHIVED"
  }
}

Handling job posting availability changes

A job posting’s availability field may switch from being non-applyable to applyable, and vice versa. As soon as this changes, you should update your UI accordingly. We recommend either hiding the job from the list of jobs you display to candidates or showing the job URL directly for the candidate to apply on the career site.

Most transitions from being applyable to non-applyable are caused by a job posting being archived. In rare cases, a job posting’s application form may change, triggering a re-parse.

Application Updated Webhook

Lifecycle

Status	Emits webhook?	Description
`PENDING`	❌	Our automated system is applying or the application is pending manual review
`SUBMITTED`	✅	The application was successfully submitted
`DUPLICATE`	✅	The ATS rejected the application because this candidate already applied
`FAILED`	✅	The application was deemed impossible to submit after human review

When can an application be marked as FAILED?If the candidate input is fundamentally invalid, and Kombo has no chance to submit the application in the candidate’s name without the candidate providing more information, the application will be marked as failed. In the future, Kombo may support flows of following up with the candidate to collect remaining data in an automated manner.In rare edge cases, when a job is taken offline while an application is in-flight, the application will also be marked as failed.

Payload

The payload follows the application schema you receive from the get application endpoint. Examples

Application is automatically submitted

{
  "id": "2Cv6VeT4efBfzvQRudprNx5z",
  "type": "ai-apply-application-status-updated",
  "data": {
    "id": "ADbmw5XSkeCSE1fAucoxEGnwZ",
    "job_posting_id": "JDn252PEYa4rMhKbJBjtn3ng",
    "status": "SUBMITTED",
    "candidate_email": "candidate@example.com",
    "proxy_email": "candidate@proxied.com",
    "created_at": "2025-01-01T00:00:00.000Z",
    "updated_at": "2025-03-02T23:12:32.000Z"
  }
}

Application is submitted after Kombo QA

{
  "id": "2Cv6VeT4efBfzvQRudprNx5z",
  "type": "ai-apply-application-status-updated",
  "data": {
    "id": "ADbmw5XSkeCSE1fAucoxEGnwZ",
    "job_posting_id": "JDn252PEYa4rMhKbJBjtn3ng",
    "status": "SUBMITTED",
    "candidate_email": "candidate@example.com",
    "proxy_email": null,
    "created_at": "2025-01-01T00:00:00.000Z",
    "updated_at": "2025-03-03T10:41:02.000Z"
  }
}

Application is marked as failed by Kombo QA (e.g., invalid candidate input)

{
  "id": "2Cv6VeT4efBfzvQRudprNx5z",
  "type": "ai-apply-application-status-updated",
  "data": {
    "id": "ADbmw5XSkeCSE1fAucoxEGnwZ",
    "job_posting_id": "JDn252PEYa4rMhKbJBjtn3ng",
    "status": "FAILED",
    "candidate_email": "candidate@example.com",
    "proxy_email": null,
    "created_at": "2025-01-01T00:00:00.000Z",
    "updated_at": "2025-03-10T08:15:00.000Z"
  }
}

General

Guides

AI Apply API Reference

Webhooks and data fetching

Overview

Data-changed webhook

Strategy

The data-changed webhook

Configuring the webhook

Fetching changes with updated_after

Keeping track of the timestamp

Job Posting Updated Webhook

Lifecycle

Payload

Handling job posting availability changes

Application Updated Webhook

Lifecycle

Payload

​Overview

​Data-changed webhook

​Strategy

​The data-changed webhook

​Configuring the webhook

​Fetching changes with updated_after

​Keeping track of the timestamp

​Job Posting Updated Webhook

​Lifecycle

​Payload

​Handling job posting availability changes

​Application Updated Webhook

​Lifecycle

​Payload

Overview

Data-changed webhook

Strategy

The data-changed webhook

Configuring the webhook

Fetching changes with updated_after

Keeping track of the timestamp

Job Posting Updated Webhook

Lifecycle

Payload

Handling job posting availability changes

Application Updated Webhook

Lifecycle

Payload