Implement BambooHR webhook endpoints with HMAC signature validation
--- name: bamboohr-webhooks-events-4d89fcc261de 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> <event-or-field-scope>" 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](references/official-docs.md) before webhook changes.--- name: bamboohr-webhooks-events-4d89fcc261de 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> <event-or-field-scope>" 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](references/official-docs.md) before webhook changes.
Imported from the listed AgentSkill.sh category. Complete supplied package files and notices are retained. Required external tools and credentials are not installed. No bundled code was executed during import. Individual agent task behavior has not been tested.