---
title: "Create Webhook"
method: POST
path: "/api/v1/webhooks"
tags: ["Webhooks", "Public API"]
---

# Create Webhook

`POST /api/v1/webhooks`

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](https://documentation.bamboohr.com/docs/webhooks), including guides for [event-based](https://documentation.bamboohr.com/docs/event-based-webhooks) and [field-based](https://documentation.bamboohr.com/docs/field-based-webhooks) webhooks.

For details on the payloads sent by each event, see the event reference:
- [employee.created](https://documentation.bamboohr.com/reference/employee-created-webhook)
- [employee.updated](https://documentation.bamboohr.com/reference/employee-updated-webhook)
- [employee.deleted](https://documentation.bamboohr.com/reference/employee-deleted-webhook)

OAuth Scopes: webhooks, webhooks.write

## 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 `201`

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

- object
  - `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 to monitor. Null when the webhook is not configured to monitor fields (e.g. event-only webhooks).
  - `postFields` object — An object 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.
  - `privateKey` string — The private key used to verify webhook authenticity via HMAC-SHA256. Only returned at creation time.
  - `includeCompanyDomain` boolean — Whether the company domain is added to the webhook request header.
  - `events` WebhookEventType[] — Events that trigger this webhook.

## 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. The response lists which `monitorFields`, `postFields`, and `unknownFields` caused the violation.
- `500` — Internal 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)