GRgreenhouse
Webhooks

Create webhook - **Greenhouse partners exclusive**

Create a partner-owned webhook subscription for a single Greenhouse event. On create, Greenhouse pings the endpoint_url to verify the connection — if the ping fails (non-2xx response or network error), the webhook is still persisted but starts with deactivated: true and must be enabled with PATCH /v3/webhooks/{id} after the endpoint is reachable. The secret_key is used to sign every delivery via HMAC-SHA256; store it on your receiver to verify the Signature header.

post/v3/webhooks

Request

  • Base URL
    https://harvest.greenhouse.io
  • URL
    https://harvest.greenhouse.io/v3/webhooks
  • Auth
    • OAuth 2
      Authorization code: https://auth.greenhouse.io/authorize
      Client credentials
      Token URL: https://auth.greenhouse.io/token scopes: harvest:webhooks:create
    • or HTTP bearer

Request body

endpoint_urlstring required

HTTPS URL Greenhouse will post the event payload to. Must use port 80, 443, 1880, 8081, 9090, or 54015. Greenhouse pings the URL on create; if the ping fails, the webhook is still saved but starts with deactivated: true.

namestring required

Human-readable label for the webhook shown in Greenhouse's Dev Center. Used for identification only.

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' required

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.

deactivatedboolean

If true, the webhook is created in a paused state and will not fire until re-enabled via PATCH /v3/webhooks/{id}. Defaults to false.

secret_keystring required

Shared secret Greenhouse combines with each payload body to produce the Signature HMAC-SHA256 header on delivery. Use the same value to verify the signature on your receiving endpoint.

basic_auth_usernamestring nullable

Username for HTTP Basic auth on the delivery request. Pair with basic_auth_password; leave both null for unauthenticated deliveries.

basic_auth_passwordstring nullable

Password for HTTP Basic auth on the delivery request. Stored encrypted; never returned on read.

additional_headersstring nullable

Extra HTTP headers to append to the delivery request, one per line in Header-Name: value format (e.g. X-Tenant: acme\r\nX-Source: greenhouse).

max_attemptsinteger required

Maximum number of delivery attempts before Sidekiq stops retrying. Must be between 1 and 7 inclusive; Greenhouse uses 6 by default.

error_recipient_emailstring nullable

Email address notified when a delivery exhausts its retries. null disables failure notifications — there is no in-app alert otherwise.

Response

Successful

idinteger
created_atstring date-time
updated_atstring date-time
namestring

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_urlstring

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_attemptsinteger

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_headersstring 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_emailstring nullable

Email address notified when a webhook delivery exhausts its retries. null disables failure notifications — there is no in-app alert otherwise.

deactivatedboolean

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_deliveredstring 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_idstring 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.

Changes

No recorded changes to this operation across all 1 revision of this API.