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.

Configuration

Webhooks can be configured by an admin user in the Account Settings section by clicking on the link "Webhooks".

By default, a BambooHR user can specify which fields they want to monitor. Currently, the list of fields that can be monitored is limited to the following, but it may expand in the future:


Address Line 1 Address Line 2 Birth Date City Compensation Change Reason Compensation: Date Country Department Division EEO Job Category Employee # Employee Tax Type Employment Status Employment Status: ACA Full-Time Employment Status: Date Ethnicity Facebook URL	First Name Gender Hire Date Home Email Home Phone Job Information: Date Job Title Last Name LinkedIn URL Location Marital Status Middle Name Mobile Phone Original Hire Date Overtime Rate Overtime Status Paid per	Pay Group Pay rate Pay Schedule Pay type Preferred Name Reporting to SSN Standard Hours Per Week State Status Time Tracking Enabled Twitter Feed Work Email Work Ext. Work Phone Zip Code

The user can also configure which fields will be posted by the webhook. Fields can be posted with an alternate name, but use BambooHR's field names (in English) by default.

Data Format

Data will be posted in the standard format of an HTML form submission or JSON. The structure will be:

Data will be posted in the JSON or the standard format of an HTML form submission. 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>][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.