Webhooks

What are Webhooks?

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.

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.

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. 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

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.