Register a webhook endpoint

Registers a publicly reachable HTTPS endpoint and subscribes it to the supplied event types.

PayrollKit returns the same signing secret in the original 201 response and an exact idempotent replay made with the original key while its result is retained. Store it securely.
List webhook endpoints never returns a signing secret. Only one registered endpoint may use a URL; registering that URL with a new idempotency key returns 409 webhook_endpoint_url_conflict without the secret.
The endpoint becomes active immediately. Registration does not send a test notification.

If the signing secret is lost, retry the unchanged registration with its original idempotency key while the result is still retained. Otherwise, remove the endpoint and register it again with a new key. The replacement receives a new endpoint ID and signing secret. Always replace the endpoint if its secret may have been compromised.

Read Keep data in sync for signature verification, delivery acknowledgement and retries.

OAuth scopes

webhooks:write

Headers

Idempotency-Key
Type: string
min length:
16
max length:
200
required

Identifies one write for safe retries. Reuse it only for the same method, URL, content type and body and, when present, the same If-Match value and acting-user headers. PayrollKit retains the result for 30 days, then treats a request using the same key as new.
X-Request-Id
Type: stringFormat: uuid

Client-generated UUID for tracing. This does not make retries safe.

Body

required

application/json

eventTypes
Type: array of "resource.changed" 1… unique!enum
const:
resource.changed
required

Notification types to send to this endpoint. resource.changed is the only supported type.
url
Type: stringFormat: uri
required

Public HTTPS URL that receives PayrollKit notifications. Only one registered endpoint may use a URL.

Responses

application/json
application/problem+json
application/problem+json
application/problem+json
application/problem+json
application/problem+json
application/problem+json

post/webhook-endpoints

Show Schema

Endpoint and signing secret

{
  "id": "webhook_7e2a91c4",
  "url": "https://api.northstarworkforce.invalid/webhooks/payrollkit",
  "eventTypes": [
    "resource.changed"
  ],
  "status": "active",
  "signingSecret": "whsec_7f3a9c2e6b1d4f8a2c6e9b4a1d8f3c7e",
  "createdAt": "2026-08-20T11:00:00Z"
}

Webhook endpoint registered