Sign in

v1

latestOpenAPI 3.1.02026-07-26294215839.4 KB
Webhooks
Public API

Update Webhook

Performs a full replacement update of a webhook — all request body fields overwrite existing values, so omitted optional fields revert to defaults. The monitorFields array must be non-empty when the webhook's events include employee.updated or employee_with_fields.updated (the default event set includes employee_with_fields.updated). The private key is not regenerated on update. Use List Webhooks to discover webhook IDs.

OAuth Scopes: webhooks, webhooks.write

put/api/v1/webhooks/{id}

Path parameters

idinteger required

The webhook ID to update.

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

The updated webhook.

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 being monitored. Null when the webhook is not configured to monitor fields (e.g. event-only webhooks).

postFieldsobject

A 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.

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_with_fields.created",
    "employee_with_fields.updated"
  ],
  "errors": [
    {
      "error": "Permission denied to the following fields",
      "postFields": [
        {
          "id": 2,
          "name": "lastName"
        }
      ]
    }
  ]
}