---
title: "Update Webhook"
method: PUT
path: "/api/v1/webhooks/{id}"
tags: ["Webhooks", "Public API"]
---

# Update Webhook

`PUT /api/v1/webhooks/{id}`

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

## Path parameters

- `id` integer, required

## Request body

- NewWebHook
  - `name` string, required — The name of the webhook.
  - `monitorFields` string[] — 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.
  - `postFields` object — 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.
  - `url` string, 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.
  - `includeCompanyDomain` boolean — If set to true, the company domain will be added to the webhook request header.
  - `events` WebhookEventType[] — 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.

## Response `200`

The updated webhook.

- WebHookResponse
  - `id` string — The ID of the webhook.
  - `name` string — The name of the webhook.
  - `created` string — Datetime when the webhook was created (UTC, format: YYYY-MM-DD HH:MM:SS).
  - `lastSent` string, nullable — Datetime when the webhook was last fired (UTC, format: YYYY-MM-DD HH:MM:SS). Null if the webhook has never fired.
  - `monitorFields` string[], nullable — A list of fields being monitored. Null when the webhook is not configured to monitor fields (e.g. event-only webhooks).
  - `postFields` object — A map of field ID or alias to the external name used in the webhook payload.
  - `url` string — The URL the webhook sends data to.
  - `format` 'json' | 'form-encoded' — The payload format used by the webhook.
  - `includeCompanyDomain` boolean — Whether the company domain is added to the webhook request header.
  - `events` WebhookEventType[] — Events that trigger this webhook.
  - `errors` WebhookSubErrorProperty[] — Field-level permission errors associated with the webhook configuration, when present.
    - `error` string
    - `unknownFields` object[]
      - `id` union
        - integer
        - string
      - `name` string
    - `monitorFields` object[]
      - `id` union
        - integer
        - string
      - `name` string
    - `duplicatePostString` string[]
    - `postFields` object[]
      - `id` union
        - integer
        - string
      - `name` string

## Other responses

- `400` — Request body is malformed or missing required fields. Common causes: missing `format`, missing `monitorFields` when required by the selected events, URL not starting with `https://`, or an invalid `format` value.
- `401` — Unauthorized.
- `403` — The authenticated user does not have permission to access one or more of the specified fields, or does not have access to the webhook. When caused by field permission violations, `errors` is an array and lists which `monitorFields`, `postFields`, and `unknownFields` caused the violation. When caused by webhook ownership denial, `errors` is an object with a single `error` string (e.g. `{"errors":{"error":"You do not have access to webhook ID: 6"}}`).
- `404` — The webhook to be updated does not exist.
- `500` — Internal server error.

---

[API](https://skmtc.net/bamboohr/apis/bamboohr-api.md) · [All operations](https://skmtc.net/bamboohr/apis/bamboohr-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/bamboohr/bamboohr-api/revisions/19ebf391a399/schema)