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

# Webhook events

> Look up every version 2 webhook event and when it fires.

Version 2 has two kinds of events. **Connector events** describe a connection: it linked, it synced, it failed, it needs relinking. **Data events** describe records: a sync created or updated records of one model.

You subscribe to each event by name. There are no wildcards, so a webhook receives exactly the events ticked on it. Version 1 events are listed on [Migrate from version 1](/guides/webhooks/migrate-from-v1#map-the-events).

## Connector events

| Event | Dashboard label | Fires when |
| - | - | - |
| `connector.linked` | Connector Linked | A new connector finishes linking and its credentials validate |
| `connector.sync.started` | Connector Sync Started | A sync job begins |
| `connector.sync.completed` | Connector Sync Completed | A sync job finishes successfully, after every data event from that sync |
| `connector.sync.failed` | Connector Sync Failed | A sync job fails |
| `connector.relink_needed` | Connector Relink Needed | A connector's credentials stop working and it moves to `RELINK_NEEDED` |
| `connector.relinked` | Connector Relinked | A connector in `RELINK_NEEDED` is reconnected and its credentials validate |

## Data events

Data events are named `<category>.<model>.<action>`, where the action is `created` or `updated`. No event reports a deleted record.

The names follow this pattern:

```
hris.employee.created
hris.employee.updated
ats.application.updated
lms.enrollment.created
```

Every model Bindbee syncs has both. Each data event fires at most once per sync, carrying the ID of every record of that model the sync created, or every one it updated - see [Webhook payload](/guides/webhooks/payload#data).

| Category | Models |
| - | - |
| `hris` | `company`, `location`, `group`, `pay_group`, `payroll_code`, `payroll_run_calendar`, `employee`, `employment`, `compensation`, `dependent`, `bank_info`, `employer_benefit`, `benefit`, `dependent_benefit`, `benefit_coverage`, `time_off`, `time_off_balance`, `timesheet_entry`, `payroll_run`, `employee_payroll_run` |
| `ats` | `department`, `office`, `remote_user`, `job`, `job_interview_stage`, `reject_reason`, `tag`, `screening_question`, `candidate`, `application`, `activity`, `attachment`, `eeoc`, `scheduled_interview`, `scorecard`, `offer` |
| `lms` | `category`, `skill`, `user`, `course`, `content`, `enrollment`, `completion` |

## Order within a sync

Bindbee sends the events of one sync one at a time, in this order:

1. `connector.sync.started`, before any data is read.
2. Every `created` event, then every `updated` event. Within each half, parent models come before the models that reference them - `hris.company` before `hris.employee`, `hris.employee` before `hris.employment` - following the order of the table above.
3. `connector.sync.completed`, last, so its `sequence` is the highest of the sync.

A failed sync sends `connector.sync.started`, then `connector.sync.failed`, then `connector.relink_needed` if the failure broke the connection.

Each event's delivery, including retries, finishes before the next starts. Across syncs and between connectors, order is not guaranteed, so sort by `sequence` - see [Delivery and retries](/guides/webhooks/delivery#order-events).

## What this means for you

* Subscribe to the models your handler processes, and nothing else.
* Size your first-sync handling for every record of every subscribed model.
* Wait for `connector.sync.completed` before acting on a sync as a whole, since the data events of that sync all precede it.
* Handle `connector.relink_needed` by asking your customer to reconnect - see [Relink a connector](/guides/troubleshooting/connector-relink).
* Run a periodic full read if you need complete data.

## Related

* [Webhook payload](/guides/webhooks/payload) - what each event carries
* [Create a webhook](/guides/webhooks/create-a-webhook) - subscribe to these events
* [Syncing](/guides/reading-writing/syncing) - when syncs run
* [Scoping](/get-started/scoping) - which models a connector syncs


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