> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stackone.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Data Sync Events

> Get notified at a webhook when a record is added to, updated in, or removed from a sync, including for providers that have no webhooks of their own.

[Data Sync](https://docs.stackone.com/optimize/data-sync/overview) can send an [event](https://docs.stackone.com/gateway/concepts/events.md) to a webhook for every record a run adds to the sync, updates, or removes from it. StackOne works out the changes itself by comparing each run's records with the ones it already stored, so an event describes what the sync saw.

Events are configured per action on a [Connector Profile](https://docs.stackone.com/connect/managing-connectors/connector-profiles.md), and every Linked Account with sync enabled for the action sends them.

## Turn on events for an action

Events are delivered to a webhook in your project. If you don't have one yet, add it on the [Webhooks](https://docs.stackone.com/connect/webhooks.md#quickstart) page first, or create it from the connector page in step 4.

**1. Open the connector**

Go to **Connectors**, open the connector, and select a saved Connector Profile. The action has to be switched on in that profile.

**2. Open the action's Data Sync panel**

Click the Data Sync icon on the action's row (**Set up Data Sync**).

**3. Choose which changes to send**

1. Turn on **Enable Data Sync**, if it isn't on already. The event toggles stay disabled until it is.
2. Under **Events**, turn on **Added Events**, **Updated Events**, **Removed Events**, or any combination.

**4. Pick the webhook**

Select the webhook under **Deliver to**, or choose **+ Add Webhook** to create one.

**5. Save**

Click **Save Changes**. Events start with the next run of each Linked Account's sync.

Subscribed actions show on the webhook's **Events** tab under **Connector**, tagged **Data Sync**, with a row for each change type (**Added**, **Updated**, **Removed**). Each change type shows **Active**, or **Paused** when it's turned off or sync for the action isn't running.

## When events are sent

Events go out once a run finishes, not the moment a record changes at the provider. How soon you hear about a change depends on **Sync every**.

| Situation | What is sent |
| - | - |
| A Linked Account's first run | Nothing. The first run sets the baseline that later runs are compared with, so it sends no `added` event for the records that already existed |
| The first run after sync was switched off for more than 30 days | Nothing. The stored records [expire after 30 days](https://docs.stackone.com/optimize/data-sync/overview#limits) without a run, so this run sets a new baseline, the same as a Linked Account's first run |
| The first run after the [lookback window](https://docs.stackone.com/optimize/data-sync/overview#lookback-window) changes | Nothing. The run rebuilds the stored records with nothing to compare them with, so it sends no events, including no `removed` event for records that fall outside the new window |
| An incremental run | `added` and `updated` events for the records it fetched |
| A full run | `added` and `updated` events, plus `removed` for every stored record the run no longer returned |
| A full run that fails, [stops early](https://docs.stackone.com/optimize/data-sync/overview#runs-that-stop-early), or is [held for its record count](https://docs.stackone.com/optimize/data-sync/overview#full-runs-held-for-their-record-count) | Nothing for that run |
| An incremental run that fails or stops early | `added` and `updated` events for the records on the pages it wrote before it stopped. The next run covers the same window again without sending them twice |
| A record that didn't change | Nothing |
| A change only in a [deeply nested field](https://docs.stackone.com/optimize/data-sync/overview#deeply-nested-data) | An `updated` event, as for any other field, unless that part was left out under the 64 KB per-record limit |

> [!WARNING]
>
> `removed` events only come from a full run. An incremental run returns only new and changed records, so only a [full run](https://docs.stackone.com/optimize/data-sync/overview#full-and-incremental-runs) can tell which stored records are no longer returned. Set **Full re-sync** to match how quickly you need to hear about them.

## Event payload

The event name is the action ID followed by the change:

* `{action_id}.added`: a record that wasn't in the stored set when the run started.
* `{action_id}.updated`: a stored record whose fields changed since the last run.
* `{action_id}.removed`: a stored record a full run no longer returned.

For example, `bamboohr_list_employees.updated`. Each change is its own request to your webhook.

A `removed` record may still exist at the provider. A full run stops returning a record when it is deleted, but also when it falls outside the action's filters or the [lookback window](https://docs.stackone.com/optimize/data-sync/overview#lookback-window), so check the record at the provider before you act on a removal as a deletion.

> [!NOTE]
>
> `added` and `removed` were named `created` and `deleted` before. Update any handler that matches on the older event names.

| Field | Type | Description |
| - | - | - |
| `event` | string | The event name, as above |
| `project_id` | string | The project the Connector Profile belongs to |
| `account_id` | string | The Linked Account the record was synced from |
| `record_type` | string | The action ID |
| `record_id` | string | The record's ID, taken from the field the action syncs on |
| `event_date` | string (ISO 8601) | When StackOne prepared the event, after the run finished |
| `sent_at` | string (ISO 8601) | When this delivery attempt was sent. Each retry gets a new value |
| `event_data` | object | The full record as Data Sync stored it, the same shape Deep Query returns. Left out of `removed` events, since there is no stored record to send |

```json theme={null}
{
  "project_id": "proj_7f3a9c",
  "account_id": "acc_42d1e8",
  "event": "bamboohr_list_employees.updated",
  "event_date": "2026-09-29T09:15:02.114Z",
  "record_type": "bamboohr_list_employees",
  "record_id": "4127",
  "sent_at": "2026-09-29T09:15:02.530Z",
  "event_data": {
    "id": "4127",
    "first_name": "Ada",
    "last_name": "Lovelace",
    "work_email": "ada@example.com",
    "department": "Engineering"
  }
}
```

`event_data` is read from the stored record when the event is prepared, after the run finishes. On a large run, preparing every event can take long enough for the next run to change the stored record first:

* If the next run updates the record, the event carries the newer version.
* If the next run removes the record, the event isn't sent, since there's no record left to send.

## Delivery

Data Sync events are signed like every other webhook event, so the same [signature verification](https://docs.stackone.com/connect/webhooks.md#verifying-webhook-signatures) applies. Their delivery works as follows:

* A delivery that doesn't get a `2xx` response is retried, starting after 5 seconds and backing off to every 10 minutes, for up to 20 attempts.
* StackOne sends each change from a run once per webhook, and its own retries don't create duplicates. Your endpoint can still receive the same event twice if it returned `200` but the response was lost, so treat a repeat of the same `event`, `record_id`, and `event_date` as a duplicate.
* Events arrive in batches and several are sent at once, so they aren't guaranteed to arrive in the order the records changed.

Every delivery attempt is logged. **View logs** at the top of the webhook's page lists them. **View logs** on a Data Sync row in the webhook's **Events** tab opens that action's sync runs instead, with **Background Logs** turned on.

## Next steps

> [card] [Data Sync](https://docs.stackone.com/optimize/data-sync/overview)
>
> Turn on sync for an action and set how often it runs.

> [card] [Webhooks](https://docs.stackone.com/connect/webhooks.md)
>
> Create the webhook Data Sync events are delivered to, and verify their signatures.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.