---

name: bamboohr-webhooks-events description: >- Create and operate BambooHR event- or field-based webhooks with one-time key custody, HMAC-SHA256 verification, idempotency, and replay controls. Use when building employee-change delivery or diagnosing webhook failures. Trigger with "BambooHR webhook", "BambooHR events", or "BambooHR webhook signature". allowed-tools: Read,Glob,Grep,Write,Edit argument-hint: "<create|receive|audit> " version: 1.5.0 license: MIT author: Jeremy Longshore jeremy@intentsolutions.io tags: [saas, hr, bamboohr, webhooks, security] model: inherit effort: high compatibility: Designed for Claude Code

BambooHR Webhook Operations

Overview

Operate permissioned BambooHR webhooks as a security boundary. The creation response contains a privateKey used for HMAC-SHA256 and returns it only once; losing it requires controlled replacement, not a retrieval call.

Prerequisites

• The target repository or integration path and the requested operator outcome.
• The tenant, identity, and data scope only when approved live work is in scope.
• The current evidence register plus customer-specific permissions and agreements.

Current Contract

• Create/list/get/update/delete and log endpoints live under /api/v1/webhooks.
• The destination URL must use HTTPS and format is required (json or form-encoded in the reviewed OpenAPI).
• monitorFields is required when events include employee.updated or employee_with_fields.updated; omitted events default to field-based employee events that also require monitored fields.
• Receiver 4xx responses are not retried. Receiver 5xx responses may be retried up to five times at documented 5, 10, 20, 40, and 80 minute intervals.

Authentication

Webhook management requires OAuth scope webhooks or a permitted API-key user. Store the one-time privateKey immediately in a secret manager scoped to tenant and webhook ID. Keep management credentials separate from receiver verification.

Instructions

1. Choose event-based or field-based delivery and list only the events, monitorFields, and postFields needed by the consumer.
2. Validate an HTTPS destination and use a non-production receiver for creation tests. Prepare secret storage before the create call.
3. Capture id and privateKey from the 201 response atomically; store the key once and ensure it never enters logs, tickets, fixtures, or source control.
4. Implement HMAC-SHA256 over the exact raw request bytes according to BambooHR's current webhook documentation. Do not parse or reserialize before checking. Confirm the documented signature carrier/header from current docs or a controlled sample; this pack does not invent one.
5. Compare signatures in constant time, reject before processing, then enforce tenant routing, payload schema, event allowlist, timestamp/replay window when supplied, and an idempotency key derived from stable delivery facts.
6. Acknowledge only after durable enqueue. Return intentional 4xx for terminal payload rejection and 5xx only when a later retry can succeed.
7. Monitor webhook logs, last-fired time, verification failures, duplicates, queue age, and dead letters. Rotate by creating and validating a replacement before removing the old webhook.

Tool Discipline

Use Read, Glob, and Grep to inspect receiver code and secret handling. Use Write/Edit only for approved handler, tests, and runbook changes. This skill does not authorize webhook creation, update, deletion, or receipt of production PII.

Approval Boundaries

Require approval for event/field scope, destination, management identity, secret write, create/update/delete calls, production traffic, and replay of any payload.

Output

Return webhook type, event/field scope, destination class, verification contract, secret custody receipt without value, idempotency strategy, receiver status policy, test results, monitoring, and rotation procedure.

Error Handling

• Creation response not stored atomically: delete or disable the unverified webhook and recreate under approval.
• Signature contract uncertain: fail closed and inspect current official docs.
• Repeated 5xx: stop accepting new side effects, preserve queue evidence, and repair before BambooHR exhausts retries.

Examples

• "Notify us when department changes" discovers the permitted field ID first.
• "Use a conventional signature header" is rejected until current official evidence confirms the exact carrier and signing input.

Resources

Read official evidence before webhook changes.