Webhook

Notify the Partner that a resource changed

​

PayrollKit sends the information needed to retrieve a changed resource. It also sends notifications when Employer, PAYE Scheme or Employment setup changes through the embedded component.

For each delivery:

  1. Read Webhook-Timestamp as Unix seconds and reject it if it differs from the current time by more than five minutes.
  2. Build the signed content from the UTF-8 bytes of the timestamp, a full stop and the exact raw request body: ${timestamp}.${rawBody}.
  3. Compute HMAC-SHA256 using the UTF-8 bytes of the signing secret, encode the digest as lowercase hexadecimal and compare Webhook-Signature with v1,<digest> using a constant-time comparison.
  4. Parse the body and confirm that Webhook-Id matches deliveryId.
  5. Save or enqueue the accepted notification somewhere that survives a restart, using deliveryId to detect duplicates.
  6. Return 204 within 10 seconds. A duplicate that has already been saved may also receive 204.

Retrieve resourceUrl asynchronously using your Partner access token. Follow the URL only when its origin is https://api.payrollkit.co; never send your token to another origin. Treat the retrieved resource as current state and do not assume notifications arrive in the same order as the changes.

A timeout, network failure or response other than 204 causes a retry after 1 minute, 5 minutes, 30 minutes, 2 hours, 12 hours and 24 hours. Retries keep the same body and deliveryId but use a new Webhook-Timestamp and Webhook-Signature. PayrollKit stops after the final retry and does not provide a replay feed. After a longer outage, list or retrieve the PayrollKit resources your product keeps in sync.

Headers

  • Webhook-Id
    Type: string
    min length:  
    1
    max length:  
    200
    required

    Delivery ID used to detect duplicates. It matches the body deliveryId and remains the same across retries.

  • Webhook-Timestamp
    Type: integerFormat: int64
    required

    Unix timestamp in seconds for this delivery attempt. Reject it when it differs from the current time by more than five minutes.

  • Webhook-Signature
    Type: string
    required

    HMAC-SHA256 signature for ${timestamp}.${rawBody} in the form v1,<lowercase-hex-digest>.

Body

required
application/json
  • deliveryId
    Type: string
    min length:  
    1
    max length:  
    200
    required

    Stable delivery ID used to detect duplicates. Retries use the same value.

  • employerId
    Type: string
    min length:  
    1
    max length:  
    200
    required

    PayrollKit ID of the Employer that owns the changed resource.

  • eventType
    const:  
    resource.changed
    required

    Type of notification.

  • occurredAt
    Type: stringFormat: date-time
    required

    When PayrollKit recorded the resource change. This does not indicate when the notification was delivered.

  • resourceId
    Type: string
    min length:  
    1
    max length:  
    200
    required

    PayrollKit ID of the changed resource.

  • resourceType
    Type: stringenum
    required

    Kind of setup, payroll or output resource to retrieve. Changes to nested Employment setup are reported as an Employment change.

    values
    employerpaye_schemeemploymentpay_runcalculationfilingpayslippayslip_deliveryaccounting_exportpension_exportpayment_instruction_file
  • resourceUrl
    Type: stringFormat: uri
    required

    Absolute PayrollKit API URL used to retrieve the current resource with a Partner access token.

Responses

  • 204

    Notification durably accepted, or a previously accepted duplicate acknowledged

  • default

    Notification not accepted; PayrollKit retries according to the documented schedule.

Request Example for postresourceChanged
{
  "deliveryId": "delivery_7c29e4b1",
  "eventType": "resource.changed",
  "occurredAt": "2026-08-20T09:12:00Z",
  "employerId": "er_7d91f2c8",
  "resourceType": "employment",
  "resourceId": "employment_4b72e190",
  "resourceUrl": "https://api.payrollkit.co/v1/employers/er_7d91f2c8/employments/employment_4b72e190"
}
No Body

Notification durably accepted, or a previously accepted duplicate acknowledged