Copy page

Recipes

Webhook listener and payroll references

Use this recipe when a payroll, finance, or HR-ops workflow needs to react to safe HollyHR changes without receiving raw payroll, bank, tax, government-id, date-of-birth, or home-address values.

Webhook payloads are notifications. Payroll readiness data is fetched separately through the export endpoint with the elevated payroll_exports:read scope.

What it uses

• POST /webhooks
• POST /webhooks/{webhookId}/test
• signed webhook deliveries
• GET /people/{personId} or GET /time-off/{timeOffId} for current state
• optional GET /payroll-readiness-export

Scopes

Webhook setup needs:

Code
webhooks:manage people:read time_off:read

The payroll readiness export needs a separate key or separately approved scope:

Code
payroll_exports:read

Keep payroll_exports:read off the webhook receiver unless that same service is explicitly approved to fetch the readiness package.

Register a listener

Code
curl -X POST "$HOLLYHR_API_BASE_URL/webhooks" \
  -H "Authorization: Bearer $HOLLYHR_API_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: idem_create_payroll_listener_001" \
  --data '{
    "name": "Payroll readiness listener",
    "url": "https://payroll-sync.example.com/hollyhr/webhooks",
    "subscribed_events": [
      "person.created",
      "person.updated",
      "person.ended",
      "person.reactivated",
      "time_off.created",
      "time_off.updated",
      "time_off.cancelled"
    ]
  }'

Store the returned signing_secret immediately. It is shown once.

Listener behavior

1. Verify the webhook signature against the raw request body.
2. Reject stale timestamps according to your tolerance.
3. Deduplicate by HollyHR-Webhook-Id.
4. Acknowledge with 2xx only after safely accepting the event.
5. Fetch current state through REST if the event affects your downstream view.

Use Receive webhooks in Node for a minimal Express receiver and Webhooks for retry, health, delivery-log, and redelivery details.

Payroll readiness handoff

The payroll readiness export is provider-neutral. It returns the hollyhr-payroll-readiness-export v1 package with operational identity, employment, org-unit, working-time, FTE, readiness gap fields, a manifest, and a README. It deliberately returns presence/gap flags rather than raw salary, bank, NI/tax/government-id, date-of-birth, or home-address values.

Fetch it only in an approved server-side job:

Code
curl "$HOLLYHR_API_BASE_URL/payroll-readiness-export" \
  -H "Authorization: Bearer $HOLLYHR_PAYROLL_EXPORT_TOKEN" \
  -H "Accept: application/json"

Use Payroll readiness export for the exact contract and boundaries.

Boundaries

• This is not a native payroll-provider connector.
• Public API webhooks currently emit for successful public API-origin writes, not every UI-origin change inside HollyHR.
• Webhook delivery logs never return payload bodies, response bodies, signatures, signing secrets, or raw delivery payload data.
• Payroll-ready does not mean payroll-certified. Treat the package as a safe handoff pack until HollyHR ships a named payroll connector or dedicated payroll-financial export.