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 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 HTTPS url only. HTTP is not supported. Additionally, BambooHR no longer recommends 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 triggered, we include a timestamp header (X-BambooHR-Timestamp) and a SHA-256 HMAC signature (X-BambooHR-Signature). To verify the authenticity and validity of the information received from BambooHR, simply call your programming language’s cryptographic HMAC function. The data going into the function needs to be the payload with the timestamp from the header appended, and the private key from the header. The resulting value can be compared with the signature.

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: "Custom webhooks" 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.