Webhook payload

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
`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

{
  "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
`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

Ignore fields you don’t recognize. A later version can add fields, and parsing strictly turns an addition into an outage.

`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"
}

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:

"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. 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:

"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`

{
  "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
`sync_name`	The job’s run number for this connector, for example `#18`

`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"
  }
}

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

hris.employee.created

Every data event has this shape. Only event, model, webhook.event, the connector’s category and integration, and the IDs differ.

{
  "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"
  }
}

connector.sync.started

{
  "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"
  }
}

connector.sync.completed

{
  "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"
  }
}

connector.sync.failed

{
  "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"
    }
  }
}

connector.relink_needed

{
  "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"
    }
  }
}

connector.linked

connector.relinked has the same shape, with "event": "connector.relinked".

{
  "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
  }
}

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

Webhook events - when each event fires
Verify webhook signatures - check the headers before trusting the body
Delivery and retries - deduplicating on id and ordering on sequence
Migrate from version 1 - how each version 1 field maps to this body

Reading & Writing Data

Extending the Model

Webhooks

SDK & MCP

Data Models

Workspace & Access

Going Live

Troubleshooting

Headers

Body

`webhook`

`connector`

`data`

`sync`

`error`

Sample payloads

​Headers

​Body

​webhook

​connector

​data

​sync

​error

​Sample payloads

​Related

Headers

Body

`webhook`

`connector`

`data`

`sync`

`error`

Sample payloads

Related