> ## 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 payload

> Look up the headers and body fields of a version 2 webhook delivery.

Every version 2 delivery is a `POST` with a JSON body. The body has the same top-level shape for every event. Only `data`, and the presence of `model` and `error`, depend on the event.

## Headers

| Header | Value |
| - | - |
| `Content-Type` | `application/json` |
| `webhook-id` | The event ID, identical to `id` in the body |
| `webhook-timestamp` | When Bindbee sent the event, in Unix seconds |
| `webhook-signature` | `v1,` followed by the signature - see [Verify webhook signatures](/guides/webhooks/verify-signatures) |
| `X-BINDBEE-WEBHOOK-SIGNATURE` | The legacy signature, sent so version 1 verification code keeps working |
| `X-BINDBEE-WEBHOOK-VERSION` | The webhook's version, for example `2026.10.06`. Not signed, so use it to route a request and nothing else |

A retry resends the same headers, including the same `webhook-timestamp`.

## Body

```json theme={null}
{
  "id": "01a0a9df-c758-720a-bae8-9dcce047dde2",
  "event": "hris.employee.created",
  "version": "2026.10.06",
  "sequence": 11,
  "model": "employee",
  "occurred_at": "2026-09-16T11:00:10.198843+00:00",
  "webhook": { … },
  "connector": { … },
  "data": [ … ],
  "sync": { … }
}
```

| Field | Present on | Description |
| - | - | - |
| `id` | All events | Unique ID of the event. Identical on every retry, and on every webhook that receives the event |
| `event` | All events | The event name. Route on this |
| `version` | All events | The webhook's version |
| `sequence` | All events | Increases with each event for this connector. Gaps are normal - see [Order events](/guides/webhooks/delivery#order-events) |
| `model` | Data events | The model name without its category, for example `employee` or `bank_info` |
| `occurred_at` | All events | When Bindbee created the event, as ISO 8601 in UTC. For data events this is after the sync finished, not when the record changed in the source system |
| `webhook` | All events | The webhook this delivery is for |
| `connector` | All events | The connector the event is about |
| `data` | All events | The event's content. Its shape depends on the event |
| `sync` | All events except `connector.linked` and `connector.relinked` | The sync job that produced the event, or `null` when none is known |
| `error` | `connector.sync.failed`, `connector.relink_needed` | What went wrong |

<Warning>
  Ignore fields you don't recognize. A later version can add fields, and parsing strictly turns an addition into an outage.
</Warning>

### `webhook`

```json theme={null}
{
  "webhook_id": "01a0a417-ce39-7799-9565-993c95eec951",
  "url": "https://example.com/webhooks/bindbee",
  "event": "hris.employee.created"
}
```

### `connector`

```json theme={null}
{
  "id": "01a0a4c6-9807-7c4b-9705-e8359ac15030",
  "integration": { "name": "BambooHR", "slug": "bamboohr" },
  "category": "HRIS",
  "origin_id": "prod_acme-inc_x1y2z3",
  "connector_status": "COMPLETE",
  "name": "Acme Inc",
  "environment": "production"
}
```

| Field | Description |
| - | - |
| `id` | The connector's Bindbee ID |
| `integration` | The source system: its display `name` and its `slug` |
| `category` | `HRIS`, `ATS` or `LMS` |
| `origin_id` | The ID you supplied for your customer when the connector was created. Use it to map an event to a customer in your own database |
| `connector_status` | The connector's status when the event was sent. `RELINK_NEEDED` means your customer must reconnect |
| `name` | The company that connected, for example your customer's name |
| `environment` | `production` or `development` |

### `data`

On a **data event**, `data` is an array of the Bindbee IDs of the records the sync created or updated. It holds every changed record of that model, with no limit on its length:

```json theme={null}
"data": [
  "01a0a4fc-a046-76bf-bd66-16218012d4e7",
  "01a0a9de-e417-79e2-b989-2f2e13f47c31"
]
```

Read the records with the `ids` filter on the model's endpoint - see [Filters](/guides/reading-writing/reading-data/filters). The IDs are the same `id` values the API returns. The response is paginated like any other read: `page_size` defaults to 50 and goes up to 200, so follow `cursor` to get the records past the first page.

On a **connector event**, `data` describes the connector's sync state:

```json theme={null}
"data": {
  "id": "01a0a4c7-48de-76e9-a7be-3a10e07787b5",
  "integration_name": "bamboohr",
  "category": "HRIS",
  "display_status": "Done",
  "last_sync_start_time": "2026-09-16T10:59:02.160714+00:00"
}
```

| Event | `display_status` |
| - | - |
| `connector.linked`, `connector.relinked`, `connector.sync.started` | `Syncing` |
| `connector.sync.completed` | `Done` |
| `connector.sync.failed`, `connector.relink_needed` | `Failed` |

`last_sync_start_time` is `null` on `connector.linked` and `connector.relinked` when the connector hasn't synced yet.

### `sync`

```json theme={null}
{
  "sync_id": "01a0a9de-bda5-7512-b7a3-4ecb67abc77d",
  "sync_type": "AUTOMATED",
  "sync_name": "#18"
}
```

| Field | Description |
| - | - |
| `sync_id` | The sync job's ID. Every event from one sync carries the same one, so use it to group a sync's events |
| `sync_type` | `AUTOMATED` for a scheduled sync, `MANUAL` for one you triggered - see [Syncing](/guides/reading-writing/syncing) |
| `sync_name` | The job's run number for this connector, for example `#18` |

### `error`

```json theme={null}
{
  "failed_at": "2026-09-16T12:01:41.784841+00:00",
  "message": "Received error response when validating the connection.",
  "detail": {
    "status_code": 404,
    "message": "No error message in headers"
  }
}
```

`failed_at` equals the event's `occurred_at`. `detail` is `{}` when there is nothing more to add. Show `message` to your team rather than branching on it, since the text can change.

## Sample payloads

<AccordionGroup>
  <Accordion title="hris.employee.created">
    Every data event has this shape. Only `event`, `model`, `webhook.event`, the connector's `category` and `integration`, and the IDs differ.

    ```json theme={null}
    {
      "id": "01a0a9df-c758-720a-bae8-9dcce047dde2",
      "event": "hris.employee.created",
      "version": "2026.10.06",
      "sequence": 11,
      "model": "employee",
      "occurred_at": "2026-09-16T11:00:10.198843+00:00",
      "webhook": {
        "webhook_id": "01a0a417-ce39-7799-9565-993c95eec951",
        "url": "https://example.com/webhooks/bindbee",
        "event": "hris.employee.created"
      },
      "connector": {
        "id": "01a0a4c6-9807-7c4b-9705-e8359ac15030",
        "integration": { "name": "BambooHR", "slug": "bamboohr" },
        "category": "HRIS",
        "origin_id": "prod_acme-inc_x1y2z3",
        "connector_status": "COMPLETE",
        "name": "Acme Inc",
        "environment": "production"
      },
      "data": [
        "01a0a4fc-a046-76bf-bd66-16218012d4e7",
        "01a0a9de-e417-79e2-b989-2f2e13f47c31"
      ],
      "sync": {
        "sync_id": "01a0a9de-bda5-7512-b7a3-4ecb67abc77d",
        "sync_type": "AUTOMATED",
        "sync_name": "#18"
      }
    }
    ```
  </Accordion>

  <Accordion title="connector.sync.started">
    ```json theme={null}
    {
      "id": "01a0a9de-c758-7413-aedb-f8979523beca",
      "event": "connector.sync.started",
      "version": "2026.10.06",
      "sequence": 15,
      "occurred_at": "2026-09-16T10:59:02.198843+00:00",
      "webhook": {
        "webhook_id": "01a0a417-ce39-7799-9565-993c95eec951",
        "url": "https://example.com/webhooks/bindbee",
        "event": "connector.sync.started"
      },
      "connector": {
        "id": "01a0a4c6-9807-7c4b-9705-e8359ac15030",
        "integration": { "name": "BambooHR", "slug": "bamboohr" },
        "category": "HRIS",
        "origin_id": "prod_acme-inc_x1y2z3",
        "connector_status": "COMPLETE",
        "name": "Acme Inc",
        "environment": "production"
      },
      "data": {
        "id": "01a0a4c7-48de-76e9-a7be-3a10e07787b5",
        "integration_name": "bamboohr",
        "category": "HRIS",
        "display_status": "Syncing",
        "last_sync_start_time": "2026-09-16T10:59:02.160714+00:00"
      },
      "sync": {
        "sync_id": "01a0a9de-bda5-7512-b7a3-4ecb67abc77d",
        "sync_type": "AUTOMATED",
        "sync_name": "#18"
      }
    }
    ```
  </Accordion>

  <Accordion title="connector.sync.completed">
    ```json theme={null}
    {
      "id": "01a0a9df-c758-7413-aedb-f8979523becb",
      "event": "connector.sync.completed",
      "version": "2026.10.06",
      "sequence": 16,
      "occurred_at": "2026-09-16T11:00:10.198843+00:00",
      "webhook": {
        "webhook_id": "01a0a417-ce39-7799-9565-993c95eec951",
        "url": "https://example.com/webhooks/bindbee",
        "event": "connector.sync.completed"
      },
      "connector": {
        "id": "01a0a4c6-9807-7c4b-9705-e8359ac15030",
        "integration": { "name": "BambooHR", "slug": "bamboohr" },
        "category": "HRIS",
        "origin_id": "prod_acme-inc_x1y2z3",
        "connector_status": "COMPLETE",
        "name": "Acme Inc",
        "environment": "production"
      },
      "data": {
        "id": "01a0a4c7-48de-76e9-a7be-3a10e07787b5",
        "integration_name": "bamboohr",
        "category": "HRIS",
        "display_status": "Done",
        "last_sync_start_time": "2026-09-16T10:59:02.160714+00:00"
      },
      "sync": {
        "sync_id": "01a0a9de-bda5-7512-b7a3-4ecb67abc77d",
        "sync_type": "AUTOMATED",
        "sync_name": "#18"
      }
    }
    ```
  </Accordion>

  <Accordion title="connector.sync.failed">
    ```json theme={null}
    {
      "id": "01a0aa18-1b98-7f12-8a5e-62ca6ee9944a",
      "event": "connector.sync.failed",
      "version": "2026.10.06",
      "sequence": 27,
      "occurred_at": "2026-09-16T12:01:41.784841+00:00",
      "webhook": {
        "webhook_id": "01a0a417-ce39-7799-9565-993c95eec951",
        "url": "https://example.com/webhooks/bindbee",
        "event": "connector.sync.failed"
      },
      "connector": {
        "id": "01a0a4c6-9807-7c4b-9705-e8359ac15030",
        "integration": { "name": "BambooHR", "slug": "bamboohr" },
        "category": "HRIS",
        "origin_id": "prod_acme-inc_x1y2z3",
        "connector_status": "COMPLETE",
        "name": "Acme Inc",
        "environment": "production"
      },
      "data": {
        "id": "01a0a4c7-48de-76e9-a7be-3a10e07787b5",
        "integration_name": "bamboohr",
        "category": "HRIS",
        "display_status": "Failed",
        "last_sync_start_time": "2026-09-16T12:01:38.938456+00:00"
      },
      "sync": {
        "sync_id": "01a0aa18-1085-7d88-9bad-81a41bb35d9f",
        "sync_type": "AUTOMATED",
        "sync_name": "#22"
      },
      "error": {
        "failed_at": "2026-09-16T12:01:41.784841+00:00",
        "message": "Received error response when validating the connection.",
        "detail": {
          "status_code": 404,
          "message": "No error message in headers"
        }
      }
    }
    ```
  </Accordion>

  <Accordion title="connector.relink_needed">
    ```json theme={null}
    {
      "id": "01a0aa18-1b99-740f-a325-16e5dc3545ad",
      "event": "connector.relink_needed",
      "version": "2026.10.06",
      "sequence": 28,
      "occurred_at": "2026-09-16T12:01:41.784841+00:00",
      "webhook": {
        "webhook_id": "01a0a417-ce39-7799-9565-993c95eec951",
        "url": "https://example.com/webhooks/bindbee",
        "event": "connector.relink_needed"
      },
      "connector": {
        "id": "01a0a4c6-9807-7c4b-9705-e8359ac15030",
        "integration": { "name": "BambooHR", "slug": "bamboohr" },
        "category": "HRIS",
        "origin_id": "prod_acme-inc_x1y2z3",
        "connector_status": "RELINK_NEEDED",
        "name": "Acme Inc",
        "environment": "production"
      },
      "data": {
        "id": "01a0a4c7-48de-76e9-a7be-3a10e07787b5",
        "integration_name": "bamboohr",
        "category": "HRIS",
        "display_status": "Failed",
        "last_sync_start_time": "2026-09-16T12:01:38.938456+00:00"
      },
      "sync": {
        "sync_id": "01a0aa18-1085-7d88-9bad-81a41bb35d9f",
        "sync_type": "AUTOMATED",
        "sync_name": "#22"
      },
      "error": {
        "failed_at": "2026-09-16T12:01:41.784841+00:00",
        "message": "Received error response when validating the connection.",
        "detail": {
          "status_code": 404,
          "message": "No error message in headers"
        }
      }
    }
    ```
  </Accordion>

  <Accordion title="connector.linked">
    `connector.relinked` has the same shape, with `"event": "connector.relinked"`.

    ```json theme={null}
    {
      "id": "01a0aa24-69b4-7b07-8071-284464571a7e",
      "event": "connector.linked",
      "version": "2026.10.06",
      "sequence": 1,
      "occurred_at": "2026-09-16T12:15:08.211961+00:00",
      "webhook": {
        "webhook_id": "01a0a417-ce39-7799-9565-993c95eec951",
        "url": "https://example.com/webhooks/bindbee",
        "event": "connector.linked"
      },
      "connector": {
        "id": "01a0a4c6-9807-7c4b-9705-e8359ac15030",
        "integration": { "name": "BambooHR", "slug": "bamboohr" },
        "category": "HRIS",
        "origin_id": "prod_acme-inc_x1y2z3",
        "connector_status": "COMPLETE",
        "name": "Acme Inc",
        "environment": "production"
      },
      "data": {
        "id": "01a0a4c7-48de-76e9-a7be-3a10e07787b5",
        "integration_name": "bamboohr",
        "category": "HRIS",
        "display_status": "Syncing",
        "last_sync_start_time": null
      }
    }
    ```
  </Accordion>
</AccordionGroup>

The dashboard shows the same samples: click the code icon beside any event on the **Add Webhook** form.

## Related

* [Webhook events](/guides/webhooks/events) - when each event fires
* [Verify webhook signatures](/guides/webhooks/verify-signatures) - check the headers before trusting the body
* [Delivery and retries](/guides/webhooks/delivery) - deduplicating on `id` and ordering on `sequence`
* [Migrate from version 1](/guides/webhooks/migrate-from-v1#map-the-payload) - how each version 1 field maps to this body


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