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:

1. Global Webhooks: Configured by administrators within the BambooHR settings interface. They monitor a predefined set of fields.
2. 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.

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.
• Table Behavior: If you monitor a field that belongs to a data table (like Job Info, Compensation, Address, etc.), the webhook may trigger whenever any field in that same table is updated, even if the specific field you are monitoring wasn't the one that changed.

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

Webhook Shortcomings

While powerful, webhooks have potential limitations. Network issues or problems on the receiving end can cause webhook deliveries to fail. They are not guaranteed to be 100% reliable.

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.