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 HTTPPOST 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:
- Any
v1entry inwebhook-signaturematches the computed signature, compared in constant time. webhook-timestampis within 300 seconds of the receiving server’s clock, which rejects replayed deliveries.- The
webhook-idhas not already been processed.
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 formwhsec_ 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:- Call Rotate Webhook Signing Secret. The new secret is returned once, as
signingSecret. - Deploy the new secret to the receiving server.
- For the next 24 hours, every delivery carries two
webhook-signatureentries: 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. - After 24 hours, only the new secret signs.
Subscription Endpoints
Subscriptions are managed through the Webhooks endpoints:- List Webhook Subscriptions
- Create Webhook Subscription
- Get Webhook Subscription
- Delete Webhook Subscription
- Rotate Webhook Signing Secret
- Revoke Previous Signing Secret