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
| Feature | Global Webhooks | Permissioned Webhooks |
|---|
| Setup | BambooHR admin UI | API (POST /webhooks/) |
| Field access | Subset of standard fields | All fields user can access |
| Auth | Shared secret | Per-webhook secret |
| Signature | SHA-256 HMAC | SHA-256 HMAC |
| Actions | Created, Updated, Deleted | Created, Updated, Deleted |
Step 2: Create a Permissioned Webhook via API
const webhook = await client.request<{
id: number;
name: string;
privateKey: string;
}>('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 },
limit: { enabled: false },
});
console.log(`Webhook ID: ${webhook.id}`);
console.log(`Private Key: ${webhook.privateKey}`);
Step 3: List and Manage Webhooks
const webhooks = await client.request<any[]>('GET', '/webhooks/');
for (const wh of webhooks) {
console.log(`${wh.id}: ${wh.name} -> ${wh.url} (${wh.status})`);
}
const detail = await client.request<any>('GET', `/webhooks/${webhook.id}/`);
const logs = await client.request<any[]>('GET', `/webhooks/${webhook.id}/log`);
for (const log of logs) {
console.log(`${log.timestamp}: ${log.statusCode} (${log.employeeId})`);
}
await client.request('DELETE', `/webhooks/${webhook.id}/`);
const fields = client.<>(, );
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 {
const age = Math.abs(Date.now() - parseInt(timestamp, 10) * 1000);
if (age > 300_000) {
console.error(`Webhook timestamp too old: ${age}ms`);
return false;
}
const payload = `${timestamp}.${rawBody.toString()}`;
const expected = crypto
.createHmac('sha256', secret)
.update(payload)
.digest('hex');
try {
return crypto.timingSafeEqual(
Buffer.from(signature, ),
.(expected, ),
);
} {
;
}
}
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' });
}
const payload = JSON.parse(req.body.toString());
res.status(200).json({ received: true });
(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[];
fields: Record<string, string>;
}[];
}
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(', ')}`);
(changedFields.() || changedFields.()) {
(id, fields);
}
(changedFields.()) {
(fields. === ) {
(id, fields);
}
}
(changedFields.()) {
(id, fields);
}
;
:
.();
(id);
;
}
}
}
() {
}
() {
}
() {
}
() {
}
() {
}
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> {
const changeKey = `bamboohr:webhook:${employeeId}:${action}:${changedFields.sort().join(',')}`;
const wasSet = await redis.set(changeKey, '1', 'EX', 3600, 'NX');
return wasSet === 'OK';
}
Step 8: Test Webhooks Locally
ngrok http 3000
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
| Issue | Cause | Solution |
|---|
| Invalid signature | Wrong webhook secret | Verify privateKey from webhook creation |
Empty changedFields | Created/Deleted action | Normal — only Updated includes changed fields |
| Missing fields in payload | Not in postFields config | Update webhook postFields configuration |
| Webhook not firing | Webhook disabled or URL unreachable | Check 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.
