Webhooks (Global)

What are Webhooks?

Webhooks are a tool that allow you to get notified when certain actions occur through payloads sent to a specified URL. They are a great way to stay updated with changes in your company account. Here at BambooHR we allow you to create webhooks to fire when changes are made to the employees. You can specify what fields to monitor and what fields to POST to you when those changes occur. BambooHR supports two different types of webhooks, Global and Permissioned. This page will outline how to create a Global Webhook.

Configuration

Webhooks can be configured by an admin user in the Account Settings section by clicking on the link "Webhooks". Webhooks are not turned on for all clients, but can be enabled at no charge by contacting support.

By default, a BambooHR user can specify which fields they want to monitor. 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
Benefit Group
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. Any field in the database can be posted. Fields can be posted with an alternate name, but use BambooHR's field names (in English) by default. If you monitor a field that belongs to a table, keep in mind that the webhook will be triggered every time the table is updated, even if the field being monitored is not updated. An example would be if you were monitoring the job title field. This belongs to the job info table so you would also be notified if the reporting to field was updated, since it belongs to the same table.

Users can specify a schedule of when they want webhooks to fire (for example, only at 12:00pm or every hour at 5 after the hour). They can also limit how often a webhook will fire by setting a maximum number of requests per interval in seconds.

Security

BambooHR will post to an HTTP or HTTPS url, but HTTPS is recommended. We no longer recommend a URL to include a token (unless a third party requires it).

Instead we recommend using a private secure key, this ensures that a request comes from BambooHR. The webhook is secured using SHA-256 HMAC. This is setup from the webhooks edit page under the "Private Key" section. Click Generate, to create a key.

176176 478478

This key can only be copied at the point of being made, once the webhook is saved it is no longer available to view, and must be regenerated if lost.

When the webhook is called, we send a timestamp header (X-BambooHR-Timestamp) and the SHA-256 HMAC signature (X-BambooHR-Signature). Calling the HMAC function specifying SHA-256, the data payload appended with the timestamp, and then the private key. The resulting value can be compared with the signature to verify that the information is coming from BambooHR and is valid.

An example in PHP on how to calculate and verify the HMAC is below. (PHP handles the headers differently, and different language may do the same. Refer to your specific language for details).

<?php
  $validHash = false;
  $data = file_get_contents('php://input');
  $privateKey = getPrivateKey(); //implement getting private key
  $timestamp = isset($_SERVER['HTTP_X_BAMBOOHR_TIMESTAMP']) ? $_SERVER['HTTP_X_BAMBOOHR_TIMESTAMP'] : null;
  $expectedHash = isset($_SERVER['HTTP_X_BAMBOOHR_SIGNATURE']) ? $_SERVER['HTTP_X_BAMBOOHR_SIGNATURE'] : null;
  if (!empty($timestamp) && !empty($expectedHash)) {
    $calculatedHash = hash_hmac('SHA256', $data . $timestamp, $privateKey);
    if (hash_equals($expectedHash, $calculatedHash)) {
      $validHash = true;
    }
  }
?>

Data Format

Employee data will be batched when possible, so that if multiple employees' data has been changed, they will be sent together.

Data will be posted in the standard format of an HTML form submission or JSON. The structure 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": [
    {
      "changedFields": [
        "Employee #",
        "First Name"
      ],
      "fields": {
        "Employee #": "9",
        "First Name": "Robert",
        "Last Name": "Smith",
        "Job Title": "Engineer"
      },
      "id": "<employeeId>"
    }
  ]
}

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: "[" and "]" will be stripped out of any field name before posting.

Custom webhooks

Some partners have configurations specific to their needs. If you are interested in becoming a BambooHR partner and creating a more customized webhook, please reach out to us.