---
updatedAt: 2026-05-26T18:36:02.000Z
agentTools:
  projectIndex: https://documentation.bamboohr.com/llms.txt
---

# 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](https://documentation.bamboohr.com/docs/field-based-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](https://documentation.bamboohr.com/reference/create-webhook#response-schemas)

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

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

<Callout icon="💡" theme="default">
  ### Event-Based Webhooks are ideal when you want a lightweight notification that a change occurred, then fetch the latest data via the [BambooHR API](https://documentation.bamboohr.com/reference/get-employee). This approach ensures you always have the most current data and avoids issues with payload size or field ordering.
</Callout>