Event-Based Webhooks

Overview

Event-Based Webhooks are the recommended way to receive notifications about employee changes in BambooHR. They use a simpler, event-driven payload format compared to Field-Based (Global) Webhooks.

When creating or editing a webhook in Account Settings > Webhooks, you can choose between Event-Based (recommended) and Field-Based data structures.

Supported Events

Event	Description
`employee.created`	An employee record was created
`employee.updated`	One or more monitored fields on an employee record were changed
`employee.deleted`	An employee record was deleted

📘
The employee.updated event requires at least one monitor field to be selected. The webhook will only fire when one of the monitored fields changes. The employee.created and employee.deleted events do not support monitor fields.

Webhook Data Format

Technical reference

Event-Based Webhooks can be posted in two encodings: JSON (recommended) or Form Post (URL-encoded form data).

When creating webhooks via the api, to receive the event based payload described here, ensure the event(s) subscribed to are `employee.update`, `employee.created`, and `employee.deleted`.

JSON Format

{
  "type": "employee.updated",
  "timestamp": "2026-01-31T18:42:00+0000",
  "data": {
    "companyId": "12345",
    "employeeId": "67890",
    "changedFields": [
      "firstName"
    ]
  }
}

Form Post Format

type=employee.updated
data[companyId]=12345
data[employeeId]=67890
data[changedFields][0]=firstName

Payload Fields

Field	Type	Description
`type`	string	The event type that triggered the webhook (e.g., `employee.updated`).
`timestamp`	string	ISO 8601 timestamp indicating when the event occurred.
`data.companyId`	string	The ID of the company where the change happened.
`data.employeeId`	string	The ID of the employee affected by the change.
`data.changedFields`	array	An array of field names that were changed. Present on `employee.updated` events.

Event-Specific Behavior

employee.created: The data object contains companyId and employeeId. No changedFields array is included.
employee.updated: The data object contains companyId, employeeId, and a changedFields array listing the names of the fields that were modified.
employee.deleted: The data object contains companyId and employeeId. No changedFields array is included.

💡
Event-Based Webhooks are ideal when you want a lightweight notification that a change occurred, then fetch the latest data via the BambooHR API. This approach ensures you always have the most current data and avoids issues with payload size or field ordering.

Updated 9 days ago