技能 编程开发 竹林人事系统Webhook处理

竹林人事系统Webhook处理

v20260423
bamboohr-webhooks-events
本技能详细介绍了如何为BambooHR设置和处理Webhook事件。内容涵盖了全局和权限型Webhook的创建与管理,重点教授了使用HMAC-SHA256进行签名验证以确保数据安全。用户可以学习如何接收和处理实时的员工增删改数据流,从而实现HR系统与其他业务系统(如薪资、考勤)的实时数据同步和自动化流程。
获取技能
142 次下载
概览

BambooHR Webhooks & Events

Overview

BambooHR supports two webhook types: global webhooks (configured in the BambooHR admin UI, subset of fields) and permissioned webhooks (created via API, access all fields the API key user can see). This skill covers creating, validating, and handling both types.

Prerequisites

  • BambooHR API key with webhook management permissions
  • HTTPS endpoint accessible from the internet
  • Webhook secret for HMAC-SHA256 signature verification

Instructions

Step 1: Understand Webhook Types

FeatureGlobal WebhooksPermissioned Webhooks
SetupBambooHR admin UIAPI (POST /webhooks/)
Field accessSubset of standard fieldsAll fields user can access
AuthShared secretPer-webhook secret
SignatureSHA-256 HMACSHA-256 HMAC
ActionsCreated, Updated, DeletedCreated, Updated, Deleted

Step 2: Create a Permissioned Webhook via API

// POST /webhooks/ — register a new webhook
const webhook = await client.request<{
  id: number;
  name: string;
  privateKey: string; // Save this — used for HMAC verification
}>('POST', '/webhooks/', {
  name: 'Employee Sync Webhook',
  monitorFields: [
    'firstName', 'lastName', 'jobTitle', 'department',
    'division', 'location', 'workEmail', 'status',
    'supervisor', 'hireDate', 'terminationDate',
  ],
  postFields: {
    firstName: 'firstName',
    lastName: 'lastName',
    jobTitle: 'jobTitle',
    department: 'department',
    status: 'status',
    workEmail: 'workEmail',
  },
  url: 'https://your-app.example.com/webhooks/bamboohr',
  format: 'json',
  frequency: { every: 0 }, // 0 = immediate, or N = batch every N minutes
  limit: { enabled: false },
});

console.log(`Webhook ID: ${webhook.id}`);
console.log(`Private Key: ${webhook.privateKey}`);
// IMPORTANT: Store the privateKey securely — it's the HMAC secret

Step 3: List and Manage Webhooks

// GET /webhooks/ — list all webhooks for this API key
const webhooks = await client.request<any[]>('GET', '/webhooks/');
for (const wh of webhooks) {
  console.log(`${wh.id}: ${wh.name} -> ${wh.url} (${wh.status})`);
}

// GET /webhooks/{id}/ — get webhook details
const detail = await client.request<any>('GET', `/webhooks/${webhook.id}/`);

// GET /webhooks/{id}/log — get webhook delivery logs
const logs = await client.request<any[]>('GET', `/webhooks/${webhook.id}/log`);
for (const log of logs) {
  console.log(`${log.timestamp}: ${log.statusCode} (${log.employeeId})`);
}

// DELETE /webhooks/{id}/ — remove a webhook
await client.request('DELETE', `/webhooks/${webhook.id}/`);

// GET /webhooks/monitor_fields — see available fields to monitor
const fields = await client.request<any>('GET', '/webhooks/monitor_fields');

Step 4: Signature Verification

BambooHR sends two headers: X-BambooHR-Signature (HMAC-SHA256 hex digest) and X-BambooHR-Timestamp.

import crypto from 'crypto';

function verifyBambooHRWebhook(
  rawBody: Buffer | string,
  signature: string,
  timestamp: string,
  secret: string,
): boolean {
  // 1. Reject timestamps > 5 minutes old (replay protection)
  const age = Math.abs(Date.now() - parseInt(timestamp, 10) * 1000);
  if (age > 300_000) {
    console.error(`Webhook timestamp too old: ${age}ms`);
    return false;
  }

  // 2. Compute expected HMAC
  const payload = `${timestamp}.${rawBody.toString()}`;
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');

  // 3. Timing-safe comparison
  try {
    return crypto.timingSafeEqual(
      Buffer.from(signature, 'hex'),
      Buffer.from(expected, 'hex'),
    );
  } catch {
    return false;
  }
}

Step 5: Webhook Handler (Express.js)

import express from 'express';

const app = express();

app.post('/webhooks/bamboohr',
  express.raw({ type: 'application/json' }),
  async (req, res) => {
    const sig = req.headers['x-bamboohr-signature'] as string;
    const ts = req.headers['x-bamboohr-timestamp'] as string;

    if (!sig || !ts || !verifyBambooHRWebhook(req.body, sig, ts, process.env.BAMBOOHR_WEBHOOK_SECRET!)) {
      console.error('Webhook signature verification failed');
      return res.status(401).json({ error: 'Invalid signature' });
    }

    // Parse the webhook payload
    const payload = JSON.parse(req.body.toString());
    // Respond immediately — process asynchronously
    res.status(200).json({ received: true });

    // Process each employee in the payload
    await processWebhookPayload(payload);
  },
);

Step 6: Handle Webhook Payload

BambooHR webhook payloads contain employee data grouped by action type.

interface BambooHRWebhookPayload {
  employees: {
    id: string;
    action: 'Created' | 'Updated' | 'Deleted';
    changedFields: string[];    // Which fields triggered this notification
    fields: Record<string, string>; // Current field values (from postFields config)
  }[];
}

async function processWebhookPayload(payload: BambooHRWebhookPayload): Promise<void> {
  for (const employee of payload.employees) {
    const { id, action, changedFields, fields } = employee;

    switch (action) {
      case 'Created':
        console.log(`New employee: ${fields.firstName} ${fields.lastName} (ID: ${id})`);
        await onEmployeeCreated(id, fields);
        break;

      case 'Updated':
        console.log(`Employee ${id} updated: ${changedFields.join(', ')}`);

        // Route to specific handlers based on what changed
        if (changedFields.includes('department') || changedFields.includes('jobTitle')) {
          await onPositionChanged(id, fields);
        }
        if (changedFields.includes('status')) {
          if (fields.status === 'Inactive') {
            await onEmployeeTerminated(id, fields);
          }
        }
        if (changedFields.includes('supervisor')) {
          await onManagerChanged(id, fields);
        }
        break;

      case 'Deleted':
        console.log(`Employee ${id} deleted`);
        await onEmployeeDeleted(id);
        break;
    }
  }
}

// Example handlers
async function onEmployeeCreated(id: string, fields: Record<string, string>) {
  // Provision accounts in external systems
  // e.g., create Slack account, set up email, assign training
}

async function onEmployeeTerminated(id: string, fields: Record<string, string>) {
  // Deprovisioning: disable accounts, revoke access, archive data
}

async function onPositionChanged(id: string, fields: Record<string, string>) {
  // Update org chart, Slack channels, access groups
}

async function onManagerChanged(id: string, fields: Record<string, string>) {
  // Update reporting hierarchy in downstream systems
}

async function onEmployeeDeleted(id: string) {
  // Remove from external systems
}

Step 7: Idempotency (Prevent Duplicate Processing)

import { Redis } from 'ioredis';

const redis = new Redis(process.env.REDIS_URL);

async function deduplicateWebhook(
  employeeId: string,
  action: string,
  changedFields: string[],
): Promise<boolean> {
  // Create a unique key for this specific change
  const changeKey = `bamboohr:webhook:${employeeId}:${action}:${changedFields.sort().join(',')}`;
  const wasSet = await redis.set(changeKey, '1', 'EX', 3600, 'NX'); // 1 hour TTL
  return wasSet === 'OK'; // true = first time, false = duplicate
}

Step 8: Test Webhooks Locally

# 1. Expose local server with ngrok
ngrok http 3000
# Note the https:// URL

# 2. Create a test webhook pointing to your ngrok URL
# Use the API to create webhook with your ngrok URL

# 3. Or manually send a test payload
curl -X POST http://localhost:3000/webhooks/bamboohr \
  -H "Content-Type: application/json" \
  -H "X-BambooHR-Timestamp: $(date +%s)" \
  -H "X-BambooHR-Signature: test" \
  -d '{"employees": [{"id":"1","action":"Updated","changedFields":["department"],"fields":{"firstName":"Jane","department":"Engineering"}}]}'

Output

  • Webhook registered via BambooHR API with monitored fields
  • HMAC-SHA256 signature verification on all incoming webhooks
  • Event routing by action type (Created, Updated, Deleted)
  • Field-specific change handlers (position, status, manager)
  • Deduplication via Redis
  • Local testing workflow with ngrok

Error Handling

IssueCauseSolution
Invalid signatureWrong webhook secretVerify privateKey from webhook creation
Empty changedFieldsCreated/Deleted actionNormal — only Updated includes changed fields
Missing fields in payloadNot in postFields configUpdate webhook postFields configuration
Webhook not firingWebhook disabled or URL unreachableCheck webhook status and logs via API

Enterprise Considerations

  • HTTPS required: BambooHR only posts to HTTPS URLs
  • Retry behavior: BambooHR retries failed deliveries; implement idempotency
  • Custom fields: Permissioned webhooks can monitor custom fields (use field IDs from /meta/fields/)
  • Batch frequency: Set frequency.every > 0 to batch multiple changes into fewer deliveries

Resources

Next Steps

For performance optimization, see bamboohr-performance-tuning.

信息
分类 编程开发
名称 bamboohr-webhooks-events
版本 v20260423
大小 10.11KB
更新时间 2026-04-28
语言