Skip to main content
Webhooks allow users to receive automatic notifications when events occur in the Payroll Integrations system.
Need webhook access? Contact partnerships@payrollintegrations.com to have the api-user-webhook-subscription role assigned to your API user.

Event Types


Webhook Delivery

When one of the events above occurs, Payroll Integrations sends an HTTP POST to your subscription’s path with a thin envelope. The envelope signifies that something happened, but it does not contain the underlying data. Use the event and event data endpoints below to fetch the details.
The delivered body is intentionally minimal and is not expected to change shape as new event types or data are added. Always fetch event details through the endpoints below rather than parsing the delivered body itself.

Webhook Signatures

Every delivery is signed with the subscription’s signing secret, following the Standard Webhooks specification. A verified signature proves the delivery came from Payroll Integrations and was not changed or replayed.

Delivery Headers

Verifying a Delivery

The signature is an HMAC-SHA256 of <webhook-id>.<webhook-timestamp>.<raw request body>. The HMAC key is the signing secret with the whsec_ prefix removed, base64-decoded — not the secret string itself. A delivery is authentic when:
  1. Any v1 entry in webhook-signature matches the computed signature, compared in constant time.
  2. webhook-timestamp is within 300 seconds of the receiving server’s clock, which rejects replayed deliveries.
  3. The webhook-id has not already been processed.
Verify against the raw request body exactly as received. Parsing and re-serializing the JSON first changes the bytes and causes verification to fail.
The official Standard Webhooks libraries (C#, Go, Java, JavaScript, PHP, Python, Ruby, Rust and others) also verify these signatures and can be used instead.
When several subscriptions share the same path, use the webhookSubscriptionId in the delivered body to select which subscription’s signing secret to verify with.

Signing Secret

Each subscription has its own signing secret, in the form whsec_ followed by a base64 string. It is returned only once, as signingSecret in the Create Webhook Subscription response, and cannot be retrieved later. Store it the same way as any other credential.
A subscription’s path must be an https URL. Requests with an http URL are rejected with 400.

Rotate a Signing Secret

Rotation replaces the secret without missing deliveries:
  1. Call Rotate Webhook Signing Secret. The new secret is returned once, as signingSecret.
  2. Deploy the new secret to the receiving server.
  3. For the next 24 hours, every delivery carries two webhook-signature entries: one from the new secret and one from the previous secret. Verification against either succeeds, so the switch can happen at any point in that window.
  4. After 24 hours, only the new secret signs.
If the previous secret may have been exposed, call Revoke Previous Signing Secret straight after rotating. The previous secret stops signing from the next delivery.
Rotating again within the 24-hour window retires the oldest secret immediately.

Subscription Endpoints

Subscriptions are managed through the Webhooks endpoints:

Modify a Subscription

Direct modification isn’t supported. To change event types or the destination URL:
  1. Create a new subscription with the desired list of events
  2. Delete the existing subscription
If the existing subscription is deleted before creating the new subscription, event notifications may be missed during the brief gap between deletion and creation.

Event Endpoints

Delivered events and their data are fetched back through the Webhooks endpoints: