Field-Based Webhooks

Overview

Field-Based Webhooks (also called Global Webhooks) deliver employee field data directly in the webhook payload. When a monitored field changes, the webhook sends the changed field names along with their new values.

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

For new integrations, we recommend using Event-Based Webhooks , which use a simpler payload and let you fetch the latest data via the API.

Supported Events

Configuration

Field-Based Webhooks support additional configuration options not available with Event-Based Webhooks:

• Post Fields: Choose which field values to include in the payload. You can include fields beyond just the ones being monitored.
• Field Name Aliases: Customize the field names used in the payload. For example, rename "First Name" to "firstName" to match your system's conventions.

Webhook Data Format

Technical reference

Field-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 field based payload described here, ensure the event(s) subscribed to are employee_with_fields.update, employee_with_fields.created, and employee_with_fields.deleted.

JSON Format

{
  "employees": [
    {
      "action": "Updated",
      "changedFields": [
        "First Name"
      ],
      "fields": {
        "First Name": "Bryony"
      },
      "id": "12345",
      "timestamp": "2026-01-31T18:42:00+0000"
    }
  ]
}

Form Post Format

employees[12345][changedFields][0]=First+name
employees[12345][First+name]=John

Payload Fields

Event-Specific Behavior

• Created: The action field is set to Created. Both changedFields and fields will be empty since this event only notifies that an employee was added.
• Updated: The action field is set to Updated. The changedFields array lists which monitored fields changed. The fields object contains the current values of all configured post fields (not just the changed ones).
• Deleted: The action field is set to Deleted. Both changedFields and fields will be empty since this event only notifies that an employee was removed.

📘

It is good practice to ignore fields in the payload that your integration does not recognize, as the structure may expand in the future.

Field Naming

By default, field names in the payload match the display names in BambooHR (e.g., "First Name", "Employee #"). You can customize these names using the Post Field Names configuration when setting up the webhook.

📘

Custom field names configured via the webhook settings will replace the default BambooHR field names in the payload. The changedFields array will also use the custom names.

💡

For new integrations, consider using Event-Based Webhooks. They provide a lightweight notification that a change occurred, and you can fetch the latest data via the BambooHR API to ensure you always have the most current values.