Syncs

Syncs are Knit’s primary way to keep your app up to date. Once you set up a sync for an integration, Knit polls the source app for changes and sends updates straight to your webhook. While polling, Knit automatically handles smart rate limit management and retries failed requests, so you don’t have to worry about hitting rate limits or handling retries manually. This push-based model eliminates the need for you to continuously pull data, which means you don’t have to manually check it. Knit pushes new or changed data to you as soon as it finds it.

Data is sent in a consistent format called Knit’s unified data model, so it always appears the same, regardless of which app the data originates from. Knit doesn’t store your data permanently; it fetches it on the fly and pushes it to you. Your code only needs to handle the webhook events as they arrive.

Types of syncs

There are three types of syncs in Knit:

Initial Sync
Delta Sync
Ad-Hoc Sync

Initial Sync

Initial Sync is the first sync that runs right after a user connects an integration. It fetches the full baseline dataset for your selected data models from the source app. For example, when you connect your company’s HR system, if you have subscribed to the relevant data models during the getting-started flow, Knit immediately collects all current employee records, active departments, and more, giving your app a complete, up-to-date snapshot to start with.

When It's Used

The initial sync is automatically triggered as soon as an integration is successfully connected (you do not need to start it manually), or it can also be started on demand via an API call. This serves to initialize your system by fetching the complete set of data from the connected source application, ensuring your database starts with an up-to-date baseline.

How it works

Knit reaches out to the connected app’s API’s and collects all the data you’ve set up to sync, like employees, departments, or other records you selected. It then sends each of these records straight to your webhook. Because this is the first time your system is receiving this data, every record will be treated as “new.”

Data events you’ll get

Since it’s the first time Knit is seeing this data, every record will be sent as a record.new event. For instance, each employee record from the HRIS will be delivered as a record.new event in the webhook payload.

Example

Let’s say you’ve just connected an HRIS integration and are looking for employee directory data. During the initial sync, Knit will send a series of record.new events for each active employee it finds. This allows you to quickly fill your database with a complete list of the company’s current employees, so you have an accurate, up-to-date employee directory right from the start.

When Knit calls your webhook, you will receive events like below:

{
  "type": "record.new",
  "model": "employee",
  "data": {
    "id": "emp_123",
    "firstName": "Alice",
    "lastName": "Doe",
    "email": "[email protected]"
    // other fields...
  }
}

Each record.new event includes the standardized data fields defined by Knit’s unified model, making it easy for your app to process employee records consistently, no matter which HR system you’re connected to.

Initial Sync

When It's Used

How it works

Data events you’ll get

Since it’s the first time Knit is seeing this data, every record will be sent as a record.new event. For instance, each employee record from the HRIS will be delivered as a record.new event in the webhook payload.

It fills your app’s database with all existing records, so you’re not missing anything that happened before the connection.

Example

When Knit calls your webhook, you will receive events like below:

{
  "type": "record.new",
  "model": "employee",
  "data": {
    "id": "emp_123",
    "firstName": "Alice",
    "lastName": "Doe",
    "email": "[email protected]"
    // other fields...
  }
}

Delta Sync

After the initial sync finishes, Knit switches to delta syncs. A delta sync is a recurring sync that runs at a regular interval to fetch incremental changes from the source app. Delta syncs ensure your app stays in sync with any updates, additions, or deletions that occur after the initial baseline.

When it’s used

Automatically scheduled by Knit to run at a configured frequency (e.g., every 24 hours, or as set for the integration). You can think of delta syncs as periodic updates. You do not need to invoke them manually; Knit’s infrastructure handles the scheduling.

How it works

During each delta sync, Knit looks for any changes in the source app since the last sync. It does this by either polling the app or utilizing its built-in webhook events, depending on the app's support. Once it finds updates, Knit sends them directly (push) to your webhook, keeping your system in sync with the latest data.

Data events you’ll get

Delta syncs emit events like:

record.new for newly added records (e.g., a new employee hired since the last sync).
record.changed for updates to existing records (e.g., an employee’s title or department changed).
record.deleted for records that were deleted or marked inactive (e.g., an employee who left the company).

Example

Suppose an employee’s profile is updated in the source HR system. During the next delta sync, Knit will send a record.changed event containing the updated employee information. If the employee is terminated, Knit will instead send a record.deleted event to reflect that change in your system.

Delta syncs run automatically on the schedule you set and will continue updating your data until you manually pause them through the Knit dashboard or API. This ensures that your data is continually kept up to date.

Sync Bookkeeping Events

Along with the regular data events, Knit also sends lifecycle events, known as sync bookkeeping events, to help you track the progress and status of each sync cycle. These are essential for monitoring, debugging, and confirming delivery completion.

sync.events.processed - Sent after a batch of changes is processed, this event includes the count of events delivered during that sync cycle. It’s useful for tracking progress and bookkeeping.
sync.events.allConsumed - Sent after all events in a sync cycle have been delivered and acknowledged, this event signals that the current delta sync iteration is fully complete. You can use it as a reliable indicator that your app has received all updates for that cycle.
Sync.heartbeat - This event is sent periodically by Knit if there are no data changes during a sync cycle. It confirms that the sync job is still active and functioning, even though there are no new records to deliver.
Sync.failed - This event is triggered if a sync cycle encounters an error and cannot complete. It indicates failure and helps you monitor and respond to issues that prevent successful data delivery.

Ad-Hoc Sync

Sometimes you don’t want to wait for the next scheduled delta sync; you need fresh data right now. That’s where ad-hoc syncs come in. An ad-hoc sync lets you manually start a sync whenever you want.

When and why to use

Use ad-hoc syncs to force an immediate data refresh. For example, if a user presses a "Sync now" button in your app, or if you want to re-sync after handling an error, you can start an ad-hoc sync. It’s useful for development/testing, or whenever you need data sooner than the next delta.

How to start

To trigger an ad-hoc sync, make a POST request to the following endpoint:

POST [https://api.getknit.dev/v1.0/sync.start](https://api.getknit.dev/v1.0/sync.start)

This API call will immediately start a sync, either initial or delta, depending on the syncType parameter passed in the API request. It runs outside the normal schedule.

You’ll need to include the following headers in your request:

Authorization: Bearer <API_KEY> – your API key for authentication
X-Knit-Integration-Id: <integration_id> – the ID of the integration you want to sync

Here, replace <integration_id> with the actual ID of the integration you want to sync. For example, if your integration ID is integ_abc123, the header would look like:

--header "X-Knit-Integration-Id: integ_abc123"

Behavior and scheduling

By default, triggering an ad-hoc sync resets the timer for the next scheduled delta sync. The next delta will be scheduled relative to when the ad-hoc sync completes, essentially starting a new countdown.

Example:

If delta syncs run every 24 hours at 5 PM, and you run an ad-hoc sync at 1 PM, the next delta sync will now run around 1:15 PM the following day (not 5 PM).

However, this default behavior can be overridden using the "honorScheduler" parameter when starting the sync.

If "honorScheduler": false (default): The next delta will be scheduled relative to the ad-hoc sync's completion.
If "honorScheduler": true: The original delta sync schedule is preserved. For instance, if a delta is scheduled at 5 PM, running a manual sync at 1 PM won’t impact that schedule.
This gives you flexibility; you can choose whether ad-hoc syncs should affect the regular sync cadence or not.

Acknowledgment: Ad-hoc syncs use the same webhook system as regular delta syncs, so you’ll receive the same event types: record.new, record.changed, and record.deleted. You’ll also get the usual sync lifecycle events, sync.events.processed, sync.events.allEmitted, and sync.events.allConsumed, which lets you track when the sync is processed and completed, just like with your scheduled syncs.

Example - Trigger an ad-hoc sync via API:

To start an ad-hoc sync via API, you might send:

curl --request POST "https://api.getknit.dev/v1.0/sync.start" \
     --header "Authorization: Bearer <API_KEY>" \
     --header "X-Knit-Integration-Id: <integration_id>" \
     --header "Content-Type: application/json" \
     --data '{ "honorScheduler": false }'

This API call will immediately start a sync for the specified integration. The integration_id tells Knit which connected account to sync and must match an active integration in your Knit dashboard.

This request starts an ad-hoc sync for the specified integration. If "honorScheduler": false, it resets the timer for the next delta sync.

Important: Whenever Knit sends events from any sync, make sure your webhook returns HTTP 200 OK after receiving events. If not, Knit retries for up to 4 days.

➤ Reference Custom Fields: If you need to include fields that aren’t part of Knit’s standard models, check out the Custom Fields section in the ‘Extending the Model’ documentation to learn how to map and sync additional fields specific to your needs.