Webhooks

What are Webhooks?

Webhooks are tools that allow external services to be notified when certain actions occur within your BambooHR account. When a specified event happens, like an update to employee information, BambooHR sends an HTTP POST request containing relevant data to a URL you specify. They are a great way to keep other systems updated with changes in your company account.

BambooHR supports two different types of webhooks, each suited for different use cases:

Global Webhooks: Configured by administrators within the BambooHR settings interface. They monitor a predefined set of fields.
Permissioned Webhooks: Created via the BambooHR API. The data they can access and send is limited by the permissions of the user who created them.

Choose the type that best fits your integration needs and technical capabilities.

Monitorable Fields

Both Global and Permissioned Webhooks allow you to monitor changes to employee data fields. The fields available for monitoring depend on the webhook type:

Global Webhooks: Monitor a predefined list of standard fields (see below).

Permissioned Webhooks: Can monitor any field the API user has permission to access. Use the Get monitor fields endpoint to see available fields.

The following standard fields can be monitored by webhooks. This list 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

Webhooks are also available for custom fields. Fields in custom tables, however, are not currently supported.

Security

Securing your webhooks is crucial to ensure data integrity and authenticity.

HTTPS Required: BambooHR will only send webhook payloads to HTTPS URLs. HTTP is not supported.
Private Key Verification (Recommended): Instead of relying on tokens in the URL, BambooHR uses a private secure key to sign webhook requests using SHA-256 HMAC. This allows your receiving application to verify that the request genuinely originated from BambooHR.
Signature Headers: When a webhook is triggered, BambooHR includes two important HTTP headers in the POST request:
- X-BambooHR-Timestamp: The timestamp when the request was sent.
- X-BambooHR-Signature: The SHA-256 HMAC signature calculated using the payload, the timestamp, and your private key.
Verification Process: Your application should recalculate the HMAC signature using the raw request body, the timestamp from the X-BambooHR-Timestamp header, and your stored private key. Compare your calculated signature with the one provided in the X-BambooHR-Signature header. If they match, the request is authentic.

Here is an example in PHP demonstrating how to calculate and verify the HMAC signature:

<?php
  $validHash = false;
  $data = file_get_contents('php://input');
  // Ensure you securely retrieve your webhook's private key
  $privateKey = getPrivateKey();
  $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) && !empty($privateKey)) {
    $calculatedHash = hash_hmac('SHA256', $data . $timestamp, $privateKey);
    // Use hash_equals for timing-attack safe comparison
    if (hash_equals($expectedHash, $calculatedHash)) {
      $validHash = true;
    }
  }

  if ($validHash) {
      // Process the webhook data
  } else {
      // Reject the request as invalid
  }
?>

(Note: Header handling ($SERVER['HTTP...']) may differ in other languages/frameworks. Refer to your specific language/framework documentation.)

Webhook Data Format

Webhook data is sent via HTTP POST request to your specified URL.

Formats: You can choose between JSON (recommended) or standard HTML form submission (application/x-www-form-urlencoded).
Batching: Employee data may be batched. If multiple employees trigger the webhook within a short period, their data might be included in a single POST request.
Structure: The payload generally includes a list or structure named employees. Each employee entry contains:
- id: The BambooHR employee ID.
- changedFields: An array listing the names (or sometimes IDs) of the fields that triggered the notification for this employee.
- fields (JSON) / Key-Value Pairs (HTML): The actual data for the fields you configured the webhook to post.
Handling Unrecognized Fields: The payload structure may evolve. Your application should be designed to gracefully ignore any fields or properties it doesn't recognize to ensure future compatibility.

Refer to the specific pages for Global Webhooks and Permissioned Webhooks for detailed payload examples in each format.

Webhook Retries

Webhook deliveries will retry up to 5 times if there are network issues or the receiving end returns a 500 level status code. Each retry will have between 0-30 seconds of random jitter to prevent multiple retries from clustering. The 5 retry attempts will happen with the following delays:

Retry 1 = immediately
Retry 2 = 5min
Retry 3 = 10min
Retry 4 = 20min
Retry 5 = 40min

Custom & Partner 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 contact us to become a BambooHR Partner.