Global Webhooks

What are Global Webhooks?

Global Webhooks in BambooHR are one of the two types of webhooks offered to notify you about changes to employee data via payloads sent to a specified URL. Unlike Permissioned Webhooks created via the API, Global Webhooks are configured by an admin or custom access level user with webhooks permissions directly within the BambooHR Account Settings. The user selects which fields to monitor from a predefined list provided by BambooHR. When a change occurs in a monitored field, the webhook triggers. The user also configures which specific data fields should be included in the notification payload sent securely over HTTPS, using a private key generated in the settings for verification.

For information about webhook security and signature verification, see the Security section on the main Webhooks page. For details on retry behavior, see Webhook Retries.

Configuration

Global Webhooks can be configured by an admin user in the Account Settings section by clicking on the link "Webhooks". Within the settings interface, you can:

• Select which fields to monitor from the available standard fields (see the Monitorable Fields section on the main Webhooks page)
• Configure which fields will be posted by the webhook
• Customize field names in the payload (fields use BambooHR's field names in English by default)

Webhook Data Format

Data will be posted in the standard format of an HTML form submission or JSON. We recommend the JSON format. For Created and Deleted actions the payload will always contain empty changedFields and fields objects in the request body since these actions are only notifying that the event took place and the Updated action tells webhooks consumers what fields have changed. The general structure for webhooks will be:

employees[<employeeId>][changedFields][0]=Employee #
employees[<employeeId>][changedFields][1]=First Name
employees[<employeeId>][Employee #]=9
employees[<employeeId>][First Name]=Robert
employees[<employeeId>][Last Name]=Smith
employees[<employeeId>][Job Title]=Engineer
employees[<employeeId>][action]="<Updated|Created|Deleted>"
employees[<employeeId>][timestamp]="<iso 8601 timestamp when the employee change occurred>"

{
  "employees": [
    {
      "changedFields": ["Employee #", "First Name"],
      "fields": {
        "Employee #": "9",
        "First Name": "Robert",
        "Last Name": "Smith",
        "Job Title": "Engineer"
      },
      "id": "<employeeId>",
      "action": "<Updated>",
      "timestamp": "<iso 8601 timestamp when the employee change occurred>"
    },
    {
      "changedFields": [],
      "fields": {},
      "id": "<employeeId>",
      "action": "<Deleted|Created>",
      "timestamp": "<iso 8601 timestamp when the employee change occurred>"
    }
  ]
}

where "changedFields" is an array of fields that were changed. If the field is included in the employee data, it will give the name of the posted field. Otherwise, a field ID will be given, and more information about the field can be looked up using the API.

More than one employeeId may be present as a key in the employees structure. While this structure will not be changed, more or less fields with different names may be sent to you, as configured by the user. In addition, in the future, we may add more context to the structure, so it is good practice to ignore fields that your webhook does not recognize.

📘

Note: "Custom webhooks" will be stripped out of any field name before posting.