v1

latestOpenAPI 3.1.02026-07-26294215839.4 KB

Webhooks

Public API

Create Webhook

Creates a new webhook for the authenticated user. The webhook will fire when the specified events occur or when any of the monitored fields change.

The monitorFields array is required when events includes employee.updated or employee_with_fields.updated. If events is omitted, it defaults to ['employee_with_fields.updated', 'employee_with_fields.deleted', 'employee_with_fields.created'], which means monitorFields is required by default. The format field is required.

The response includes a privateKey that should be used to verify the authenticity of incoming webhook payloads via HMAC-SHA256. This key is only returned at creation time and cannot be retrieved again.

For more details refer to the webhooks documentation, including guides for event-based and field-based webhooks.

For details on the payloads sent by each event, see the event reference:

OAuth Scopes: webhooks, webhooks.write

post/api/v1/webhooks

Request body

namestring required

The name of the webhook.

monitorFieldsstring[]

A list of fields to monitor. At least one field is required to be monitored if events is empty or contains employee_with_fields.updated or employee.updated.

postFieldsobject

An object map of field ID or alias to the external name used in the webhook payload (e.g. {"firstName": "First Name"}). Omit or send an empty object to include no extra fields.

urlstring required

The url the webhook should send data to (must begin with https://).

format'json' | 'form-encoded' required

The payload format the webhook uses. Required.

includeCompanyDomainboolean

If set to true, the company domain will be added to the webhook request header.

eventsWebhookEventType[]

Events that trigger this webhook. Defaults to ['employee_with_fields.updated', 'employee_with_fields.deleted', 'employee_with_fields.created'] if not specified. Cannot mix employee_with_fields events with employee events.

Example request

{
  "name": "My new webhook",
  "monitorFields": [
    "firstName",
    "lastName"
  ],
  "postFields": {
    "firstName": "Name",
    "lastName": "Surname",
    "dateOfBirth": "DOB"
  },
  "format": "json",
  "events": [
    "employee.created",
    "employee.updated",
    "employee.deleted"
  ]
}

Response

Webhook created successfully. The privateKey field is only returned in this response and cannot be retrieved again.

idstring

The ID of the webhook.

namestring

The name of the webhook.

createdstring

Datetime when the webhook was created (UTC, format: YYYY-MM-DD HH:MM:SS).

lastSentstring nullable

Datetime when the webhook was last fired (UTC, format: YYYY-MM-DD HH:MM:SS). Null if the webhook has never fired.

monitorFieldsstring[] nullable

A list of fields to monitor. Null when the webhook is not configured to monitor fields (e.g. event-only webhooks).

postFieldsobject

An object map of field ID or alias to the external name used in the webhook payload.

urlstring

The URL the webhook sends data to.

format'json' | 'form-encoded'

The payload format used by the webhook.

privateKeystring

The private key used to verify webhook authenticity via HMAC-SHA256. Only returned at creation time.

includeCompanyDomainboolean

Whether the company domain is added to the webhook request header.

eventsWebhookEventType[]

Events that trigger this webhook.

Example response

{
  "id": "4",
  "name": "Example Webhook",
  "created": "2021-09-20 22:38:01",
  "lastSent": "2021-09-20 22:38:01",
  "monitorFields": [
    "firstName",
    "lastName"
  ],
  "postFields": {
    "firstName": "Name",
    "lastName": "Surname",
    "dateOfBirth": "DOB"
  },
  "url": "https://www.example.com",
  "format": "json",
  "events": [
    "employee.created",
    "employee.updated",
    "employee.deleted"
  ]
}