Help Center
Webhooks

What's included in a webhook payload?

Updated 4 days ago

Every version 2 webhook payload has the same top-level shape. Route on the top-level event, because the shape of data depends on the event.

This article covers version 2 webhooks. Version 1 webhooks (2025.01.01) send a different payload and will be deprecated on December 31, 2026. See Migrate from Webhooks Version 1.

Key

What it contains

id

The event's unique ID. It stays the same on every retry

event

The event name, for example connector.sync.completed. Route on this

version

The webhook's version, for example 2026.10.06

sequence

A number that increases with each event for the connector. Gaps are normal

model

Only on data events: the model name, for example employee

occurred_at

When we created the event, in UTC. For data events, this is after the sync finished, not when the record changed in the source system

webhook

The webhook ID, its URL and the event

connector

The connector: id, integration (its name and slug), category, origin_id, connector_status, name and environment

data

The event details. The shape depends on the event

sync

The sync job: sync_id, sync_type and sync_name. Not included on connector.linked or connector.relinked, and null on other events when no sync is known

error

Only on connector.sync.failed and connector.relink_needed: when the failure happened and what went wrong

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

Match a webhook to your customer

connector.origin_id is the unique ID you gave the connector when you created it: the Unique Customer ID for a Magic Link, or origin_id in the Embedded SDK. Use it to find the customer in your own database without storing Bindbee connector IDs. connector.environment tells you whether the event came from a production or development connector.

Process each event once

A retried delivery carries the same id. Record each id you process and skip any you've already seen.

sync.sync_id is the same on every event from one sync job, so use it to group a sync's events, for example to pair a connector.sync.started with the connector.sync.completed that closes it.

Tell scheduled and manual syncs apart

sync.sync_type is AUTOMATED for a scheduled sync and MANUAL for a sync someone triggered, for example with Force Sync. This matters if you normally read only changed records with modified_after: after a manual resync run to recover missing data, you may want a full read instead.

What data contains for each event

Event

data

connector.linked, connector.relinked, connector.sync.started

An object describing the connector's sync state, with display_status of Syncing

connector.sync.completed

The same object, with display_status of Done

connector.sync.failed, connector.relink_needed

The same object, with display_status of Failed

Data events, such as hris.employee.created or hris.benefit.updated

An array of the Bindbee IDs of every record of that model the sync created (on a .created event) or updated (on an .updated event)

On a data event, each ID belongs to the model in model. For hris.benefit.* events, the IDs are benefit IDs, not employee IDs. Fetch the records from that model's endpoint using its ids filter. The array has no length limit, and that read is paginated like any other, so follow cursor to get every record.

Sample payload

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

Sample bodies for every event are in the webhook payload reference, and in the dashboard: click the code icon beside any event on the Add Webhook form.

To know when a new connector is ready, wait for its first connector.sync.completed. connector.linked fires when linking finishes and the credentials validate, before the first sync completes.

Was this helpful?
Was this helpful?