---
title: "Update webhook - **Greenhouse partners exclusive**"
method: PATCH
path: "/v3/webhooks/{id}"
tags: ["Webhooks"]
---

# Update webhook - \*\*Greenhouse partners exclusive\*\*

`PATCH /v3/webhooks/{id}`

## Request

- Base URL: `https://harvest.greenhouse.io`
- URL: `https://harvest.greenhouse.io/v3/webhooks/{id}`
- Auth: one of:
  - OAuth 2
    - Authorization code: `https://auth.greenhouse.io/authorize`
    - Client credentials
    - Token URL: `https://auth.greenhouse.io/token` scopes: `harvest:webhooks:update`
  - HTTP bearer

Update a partner-owned webhook subscription. All fields are optional — only supplied keys are written. Common uses are flipping `deactivated` to pause or resume delivery, rotating `secret_key`, and pointing `endpoint_url` at a new receiver. Updating `endpoint_url` does not re-run the create-time ping; verify the new URL out of band.

## Path parameters

- `id` integer, required

## Request body

- object
  - `endpoint_url` string: HTTPS URL Greenhouse posts the event payload to. Must use port 80, 443, 1880, 8081, 9090, or 54015.
  - `name` string: Human-readable label for the webhook shown in Greenhouse's Dev Center.
  - `event_action_type` 'application_updated' | 'candidate_anonymized' | 'candidate_stage_change' | 'delete_application' | 'delete_candidate' | 'department_deleted' | 'hire_candidate' | 'interview_deleted' | 'job_approved' | 'job_created' | 'job_deleted' | 'job_interview_stage_deleted' | 'job_post_created' | 'job_post_deleted' | 'job_post_updated' | 'job_updated' | 'merge_candidate' | 'new_candidate_application' | 'new_prospect_application' | 'offer_approved' | 'offer_created' | 'offer_deleted' | 'offer_updated' | 'office_deleted' | 'reject_candidate' | 'scorecard_deleted' | 'unhire_candidate' | 'unreject_candidate' | 'update_candidate': Greenhouse event that fires this webhook (e.g. `hire_candidate`, `candidate_stage_change`). A webhook listens to exactly one event type.
  - `deactivated` boolean: Set to `true` to pause delivery on this webhook, or `false` to re-enable a previously paused webhook.
  - `secret_key` string: Shared secret Greenhouse combines with each payload body to produce the `Signature` HMAC-SHA256 header on delivery. Rotating this value invalidates the previous signing key for future deliveries.
  - `basic_auth_username` string, nullable: Username for HTTP Basic auth on the delivery request. Pair with `basic_auth_password`; set both to `null` to remove Basic auth.
  - `basic_auth_password` string, nullable: Password for HTTP Basic auth on the delivery request. Stored encrypted; never returned on read.
  - `additional_headers` string, nullable: Extra HTTP headers to append to the delivery request, one per line in `Header-Name: value` format. Set to `null` to clear all custom headers.
  - `max_attempts` integer: Maximum number of delivery attempts before Sidekiq stops retrying. Must be between 1 and 7 inclusive.
  - `error_recipient_email` string, nullable: Email address notified when a delivery exhausts its retries. Set to `null` to disable failure notifications.

## Response `200`

Successful

- object
  - `id` integer
  - `created_at` string, date-time
  - `updated_at` string, date-time
  - `name` string: Human-readable label for the webhook shown in Greenhouse's Dev Center (e.g. `Workday hire export`). Used only for identification — does not affect delivery.
  - `endpoint_url` string: HTTPS URL Greenhouse posts the event payload to. Must use port 80, 443, 1880, 8081, 9090, or 54015. Greenhouse pings this URL on create; if the ping fails, the webhook is still saved but starts in a deactivated state.
  - `event_action_type` 'application_updated' | 'candidate_anonymized' | 'candidate_stage_change' | 'delete_application' | 'delete_candidate' | 'department_deleted' | 'hire_candidate' | 'interview_deleted' | 'job_approved' | 'job_created' | 'job_deleted' | 'job_interview_stage_deleted' | 'job_post_created' | 'job_post_deleted' | 'job_post_updated' | 'job_updated' | 'merge_candidate' | 'new_candidate_application' | 'new_prospect_application' | 'offer_approved' | 'offer_created' | 'offer_deleted' | 'offer_updated' | 'office_deleted' | 'reject_candidate' | 'scorecard_deleted' | 'unhire_candidate' | 'unreject_candidate' | 'update_candidate': Greenhouse event that fires this webhook (e.g. `hire_candidate`, `candidate_stage_change`, `job_post_created`, `offer_created`). A webhook listens to exactly one event type.
  - `max_attempts` integer: Maximum number of delivery attempts Sidekiq will make before giving up. Must be between 1 and 7 inclusive; defaults to 6 in Greenhouse. Failed attempts are retried with exponential backoff.
  - `additional_headers` string, nullable: Extra HTTP headers Greenhouse appends to the delivery request, one per line in `Header-Name: value` format (e.g. `X-Tenant: acme\r\nX-Source: greenhouse`). `null` when no custom headers are configured.
  - `error_recipient_email` string, nullable: Email address notified when a webhook delivery exhausts its retries. `null` disables failure notifications — there is no in-app alert otherwise.
  - `deactivated` boolean: If `true`, the webhook is paused and will not fire on its event. Set automatically when a newly created webhook fails its initial ping; can be toggled by partners through `PATCH /v3/webhooks/{id}`.
  - `last_delivered` string, date-time, nullable: Timestamp of the most recent successful delivery, in ISO 8601. `null` when the webhook has never delivered a payload (including newly created webhooks).
  - `client_id` string, nullable: The `client_id` of the partner client application that owns this webhook. A webhook is owned by the application that created it through the API; ownership scopes which application can see and modify it. `null` when the webhook is unattributed — created in the Greenhouse Dev Center, or before provenance tracking — in which case every one of the partner's applications can see and modify it.

## Other responses

- `401`: Unauthorized
- `403`: Forbidden
- `422`: Unprocessable Content

---

[API](https://skmtc.dev/greenhouse/apis/harvest-api.md) - [All operations](https://skmtc.dev/greenhouse/apis/harvest-api/llms.txt) - [OpenAPI document](https://skmtc.dev/greenhouse/apis/harvest-api/revisions/822822e3f771?raw)