Create Webhook

post

https://{companyDomain}.bamboohr.com/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, including guides for event-based and field-based webhooks.

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

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Body Params

name

string

required

The name of the webhook.

monitorFields

array of strings

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.

monitorFields

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

string

enum

required

The payload format the webhook uses. Required.

Allowed:

includeCompanyDomain

boolean

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

events

array of objects

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.

events

Responses

Language

Credentials

URL

Loading…

Response

Click Try It! to start a request and see the response here! Or choose an example:

application/json

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

400Request 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.

401Unauthorized.

403The 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.

500Internal error