--- updatedAt: 2025-06-12T11:23:22.000Z --- Fetch the complete documentation index at: https://docs.recruitee.com/llms.txt. Use this file to discover all available pages before exploring further. Append .md to any documentation page URL to get its markdown version. # Webhooks Webhooks allow you to receive notifications when events happen in Recruitee. They may be used standalone or as a complement to the [Recruitee JSON API](https://docs.recruitee.com/reference#reference-getting-started). Once a webhook is configured, Recruitee will send HTTP POST requests to the given URL whenever one of the chosen events occurs. # Configuring webhooks *** To manage webhooks, a team member's role needs to have the "Manage webhooks" ability assigned in their [hiring role](https://app.recruitee.com/#/settings/roles) under Add-ons. "Manage webhooks" ability Configure webhooks under [Settings > Apps and Plugins > Webhooks](https://app.recruitee.com/#/settings/webhooks/overview) by clicking **+ New webhook**. Webhook configuration dialog `Name` can be filled in with anything meaningful to you. Fill in the endpoint that Recruitee should send notifications to under `POST URL`; you need to use HTTPS. Select the events you are interested in. It is fine not to select any events yet - you can adjust that later on. The `Test` button prompts Recruitee to send a test request to your endpoint. A special `test` parameter is included in the request so that you know it's not a real event. When developing your service, make sure that you handle this parameter. Example test request: ```http POST /your-path HTTP/1.1 Content-Type: application/json User-Agent: Recruitee-Webhooks {"test":true} ``` You can also use the `Test payload` buttons. They work just like the `Test` button, but the requests carry example event payloads in addition to the `test` parameter. To successfully `Verify and create` a webhook configuration, your service needs to respond with `200` HTTP status to the test request. # Request log *** Every request is logged for 30 days. You can find the request log under Settings > Apps and Plugins > Webhooks in the [Logs tab](https://app.recruitee.com/#/settings/webhooks/logs). Upon revealing request details, you'll see the request body, response, next attempt at (in case of a failure), as well as options to cancel the automatic retry and retry the request immediately. # Delivery guarantees *** Any response status other than `200` is considered a webhook delivery failure. Recruitee will then keep trying to deliver the webhook. Each successive retry will be delayed more and more, for up to nine attempts: * the 1st retry will happen after one minute * the 2nd retry will happen 3 minutes after the 1st one has failed * the 3rd retry - 10 minutes after * the 4th retry - 45 minutes after * 5th - 2 hours * 6th - 5 hours * 7th - 10 hours * 8th - 24 hours * 9th retry - 48 hours The next scheduled attempt date for each request can be found on the [Logs tab](https://app.recruitee.com/#/settings/webhooks/logs). Requests will timeout after 10 seconds. Make sure your service responds within this time frame. # Rate limiting *** Trial companies are limited to 5 requests per minute. All others have the quota of 100 requests per minute. When the company reaches its limit, any subsequent webhook requests get delayed by 10 +/- 5 minutes. # Webhook verification *** We strongly recommend that you verify the webhooks we send. You can do that thanks to the `X-Recruitee-Signature` header we include in all HTTP requests and the webhook secret you can find under [Settings > Apps and Plugins > Webhooks](https://app.recruitee.com/#/settings/webhooks/overview). Webhook secret The value of `X-Recruitee-Signature` header is a base16-encoded (hexadecimal) HMAC-SHA256 digest of the webhook secret and body of the HTTP request. For example, let us assume that your secret is `DuP4ej5yyJB5TIrIEI/dCtJN7sHj`, and the HTTP request looks as follows: ```http POST /your-path HTTP/1.1 Content-Type: application/json User-Agent: Recruitee-Webhooks X-Recruitee-Signature: 3b64e3049cb9e108fbb18a453e909cb4a32e3ae140ea01d84c2b5d316c19162f {"attempt_count":1,"created_at":"2020-12-14T04:47:33.905241Z","event_subtype":"stage_changed","event_type":"candidate_moved","id":30,"payload":{"candidate":{"created_at":"2020-12-09T14:36:56.578000Z","emails":[],"id":975539,"name":"test","phones":[],"photo_thumb_url":"https://recruitee-staging.s3.eu-central-1.amazonaws.com/candidates/975539/thumb_photo_anydaa715ph6.png","referrer":null,"source":"manual","updated_at":"2020-12-09T14:37:01.119831Z"},"company":{"id":5943,"name":"MP company 2"},"details":{"from_stage":{"id":911876,"name":"Phone interview"},"to_stage":{"id":911877,"name":"On-site interview"}},"offer":{"created_at":"2020-12-09T14:37:59.875608Z","department":null,"id":269122,"kind":"job","slug":"test-job","tags":[],"title":"test job","updated_at":"2020-12-09T14:38:17.539041Z"}}} ``` To verify the webhook request, you need to recreate those steps in your service: ```shell $ SECRET='DuP4ej5yyJB5TIrIEI/dCtJN7sHj' $ BODY='{"attempt_count":1,"created_at":"2020-12-14T04:47:33.905241Z","event_subtype":"stage_changed","event_type":"candidate_moved","id":30,"payload":{"candidate":{"created_at":"2020-12-09T14:36:56.578000Z","emails":[],"id":975539,"name":"test","phones":[],"photo_thumb_url":"https://recruitee-staging.s3.eu-central-1.amazonaws.com/candidates/975539/thumb_photo_anydaa715ph6.png","referrer":null,"source":"manual","updated_at":"2020-12-09T14:37:01.119831Z"},"company":{"id":5943,"name":"MP company 2"},"details":{"from_stage":{"id":911876,"name":"Phone interview"},"to_stage":{"id":911877,"name":"On-site interview"}},"offer":{"created_at":"2020-12-09T14:37:59.875608Z","department":null,"id":269122,"kind":"job","slug":"test-job","tags":[],"title":"test job","updated_at":"2020-12-09T14:38:17.539041Z"}}}' $ echo -n $BODY | openssl dgst -sha256 -hmac $SECRET 3b64e3049cb9e108fbb18a453e909cb4a32e3ae140ea01d84c2b5d316c19162f ``` As you can see, we have arrived at the same result as the contents of `X-Recruitee-Signature` header. This confirms that Recruitee sent the webhook and its body is intact. # Event structure *** The body of each HTTP request sent by Recruitee contains an event. All events share a common structure. | Field | Type/format | Description | | :------------- | :----------- | :----------------------------------------------------------------------------------------------------------------------------------------- | | id | integer | Uniquely identifies the event. Subsequent delivery retries will have the same `id`. | | attempt\_count | integer | The count of attempts Recruitee has made to deliver the given event. It starts at 1. Subsequent delivery retries increment it by 1. | | created\_at | ISO 8601 UTC | When the event originally happened. Does not change with subsequent delivery retries. | | event\_type | string | Indicates which event this is. For information on supported events, see the detailed event documentation below. | | event\_subtype | string | Contains more information about the event. For information on possible values, see the detailed event documentation below. | | payload | map | Data related to the event, different for each event type. For information on possible values, see the detailed event documentation below. | ## Candidate created Triggered when a new candidate applies or is created. Example request body: ```json { "attempt_count": 1, "created_at": "2020-12-11T23:50:56.168592Z", "event_subtype": "manual", "event_type": "new_candidate", "id": 73, "payload": { "candidate": { "created_at": "2020-12-11T23:50:54.110368Z", "emails": [ "john.doe@mail.com" ], "id": 21056, "name": "John Doe", "phones": [ "123123123" ], "photo_thumb_url": "https://recruitee-dev.s3.eu-central-1.amazonaws.com/candidates/21056/thumb_photo_vweaseucrbtp.png", "source": "manual", "updated_at": "2020-12-11T23:50:54.110368Z" }, "company": { "id": 1, "name": "Devtest Company" }, "offers": [ { "created_at": "2018-07-10T10:29:15.000000Z", "department": { "id": 9, "name": "Maritime" }, "id": 617, "kind": "job", "locations": [ { "country_code": "DE", "full_address": "Germany, Saarland, Düsseldorf, 90910, Saarlander Street", "id": 8, "state_code": "SL" }, { "country_code": "PL", "full_address": "Poland, Wielkopolskie, Poznań, 61-248, Polish Street", "id": 63, "state_code": "WP" } ], "slug": "cruiser-captain", "tags": [], "title": "Cruiser Captain", "updated_at": "2020-12-11T23:50:55.835946Z" } ] } } ``` | Field | Type/format | Description | | :---------------- | :--------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------- | | event\_type | string | Always equals "new\_candidate". | | event\_subtype | string | Can be "email", "career\_site", "manual", or "imported" to indicate the way the candidate was created. | | payload.candidate | [Candidate](https://docs.recruitee.com/docs/webhooks#candidate) | New candidate. | | payload.company | [Company](https://docs.recruitee.com/docs/webhooks#simpleentity) | | | payload.offers | [Offer](https://docs.recruitee.com/docs/webhooks#offer)\[] | Offers the new candidate was assigned to on creation. | ## Candidate assigned Triggered when a new or existing candidate is assigned to a job or talent pool. Example request body: ```json { "attempt_count": 1, "created_at": "2020-12-11T23:50:56.233856Z", "event_subtype": "manual", "event_type": "candidate_assigned", "id": 74, "payload": { "candidate": { "created_at": "2020-12-11T23:50:54.110368Z", "emails": [ "john.doe@mail.com" ], "id": 21056, "name": "John Doe", "phones": [ "123123123" ], "photo_thumb_url": "https://recruitee-dev.s3.eu-central-1.amazonaws.com/candidates/21056/thumb_photo_vweaseucrbtp.png", "source": "manual", "updated_at": "2020-12-11T23:50:54.110368Z" }, "company": { "id": 1, "name": "Devtest Company" }, "offer": { "created_at": "2018-07-10T10:29:15.000000Z", "department": { "id": 9, "name": "Maritime" }, "id": 617, "kind": "job", "locations": [ { "country_code": "DE", "full_address": "Germany, Saarland, Düsseldorf, 90910, Saarlander Street", "id": 8, "state_code": "SL" }, { "country_code": "PL", "full_address": "Poland, Wielkopolskie, Poznań, 61-248, Polish Street", "id": 63, "state_code": "WP" } ], "slug": "cruiser-captain", "tags": [], "title": "Cruiser Captain", "updated_at": "2020-12-11T23:50:55.835946Z" }, "placement_locations": [ { "country_code": "DE", "full_address": "Germany, Saarland, Düsseldorf, 90910, Saarlander Street", "id": 8, "state_code": "SL" } ] } } ``` | Field | Type/format | Description | | :--------------------------- | :------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------ | | event\_type | string | Always equals "candidate\_assigned". | | event\_subtype | string | Can be "email", "career\_site", "manual", or "imported" to indicate the way the candidate was assigned to an offer. | | payload.candidate | [Candidate](https://docs.recruitee.com/docs/webhooks#candidate) | Assigned candidate. | | payload.company | [Company](https://docs.recruitee.com/docs/webhooks#simpleentity) | | | payload.offer | [Offer](https://docs.recruitee.com/docs/webhooks#offer) | Offer the candidate was assigned to. | | payload.placement\_locations | [PlacementLocations](https://docs.recruitee.com/docs/webhooks#placementlocation) | Offer locations the candidate has been assigned to. | ## Move on pipeline Triggered when a candidate is moved to a different pipeline change, disqualified or requalified. ```json { "attempt_count": 1, "created_at": "2020-12-12T00:30:01.860998Z", "event_subtype": "stage_changed", "event_type": "candidate_moved", "id": 75, "payload": { "candidate": { "created_at": "2020-12-11T23:50:54.110368Z", "emails": [ "john.doe@mail.com" ], "id": 21056, "name": "John Doe", "phones": [ "123123123" ], "photo_thumb_url": "https://recruitee-dev.s3.eu-central-1.amazonaws.com/candidates/21056/thumb_photo_vweaseucrbtp.png", "source": "manual", "updated_at": "2020-12-11T23:50:54.110368Z" }, "company": { "id": 1, "name": "Devtest Company" }, "details": { "from_stage": { "id": 5716, "name": "Applied", "category": "apply" }, "to_stage": { "id": 4110, "name": "Phone interview", "category": "phone_screen" } }, "offer": { "created_at": "2018-07-10T10:29:15.000000Z", "department": { "id": 9, "name": "Maritime" }, "id": 617, "kind": "job", "locations": [ { "country_code": "DE", "full_address": "Germany, Saarland, Düsseldorf, 90910, Saarlander Street", "id": 8, "state_code": "SL" }, { "country_code": "PL", "full_address": "Poland, Wielkopolskie, Poznań, 61-248, Polish Street", "id": 63, "state_code": "WP" } ], "slug": "cruiser-captain", "tags": [], "title": "Cruiser Captain", "updated_at": "2020-12-11T23:50:55.835946Z" }, "placement_locations": [ { "country_code": "DE", "full_address": "Germany, Saarland, Düsseldorf, 90910, Saarlander Street", "id": 8, "state_code": "SL" } ] } } ``` | Field | Type/format | Description | | :--------------------------- | :-------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | event\_type | string | Always equals "candidate\_moved". | | event\_subtype | string | Can be "stage\_changed", "disqualified", or "requalified" to indicate the way the candidate's state was changed. `event_subtype` affect the contents of the `payload.details` field. | | payload.candidate | [Candidate](https://docs.recruitee.com/docs/webhooks#candidate) | Candidate whose status was changed. | | payload.company | [Company](https://docs.recruitee.com/docs/webhooks#simpleentity) | | | payload.offer | [Offer](https://docs.recruitee.com/docs/webhooks#offer) | Offer the status change was related to. | | payload.details | [CandidateMovedDetails](https://docs.recruitee.com/docs/webhooks#candidatemoveddetails) | Additional details about the change, format depends on `event_subtype`. | | payload.placement\_locations | [PlacementLocations](https://docs.recruitee.com/docs/webhooks#placementlocation) | Offer locations the candidate was assigned to | ## Candidate deleted Triggered when a candidate is deleted. Example request body: ```json { "attempt_count": 1, "created_at": "2020-12-11T23:50:56.168592Z", "event_subtype": "manual", "event_type": "candidate_deleted", "id": 73, "payload": { "candidate": { "created_at": "2020-12-11T23:50:54.110368Z", "emails": [ "john.doe@mail.com" ], "id": 21056, "name": "John Doe", "phones": [ "123123123" ], "photo_thumb_url": "https://recruitee-dev.s3.eu-central-1.amazonaws.com/candidates/21056/thumb_photo_vweaseucrbtp.png", "source": "manual", "updated_at": "2020-12-11T23:50:54.110368Z" }, "company": { "id": 1, "name": "Devtest Company" }, "offers": [ { "created_at": "2018-07-10T10:29:15.000000Z", "department": { "id": 9, "name": "Maritime" }, "id": 617, "kind": "job", "locations": [ { "country_code": "DE", "full_address": "Germany, Saarland, Düsseldorf, 90910, Saarlander Street", "id": 8, "state_code": "SL" }, { "country_code": "PL", "full_address": "Poland, Wielkopolskie, Poznań, 61-248, Polish Street", "id": 63, "state_code": "WP" } ], "slug": "cruiser-captain", "tags": [], "title": "Cruiser Captain", "updated_at": "2020-12-11T23:50:55.835946Z" } ] } } ``` | Field | Type/format | Description | | :---------------- | :--------------------------------------------------------------- | :-------------------------------------------- | | event\_type | string | Always equals "candidate\_deleted". | | event\_subtype | string | Always equals "manual". | | payload.candidate | [Candidate](https://docs.recruitee.com/docs/webhooks#candidate) | Deleted candidate. | | payload.company | [Company](https://docs.recruitee.com/docs/webhooks#simpleentity) | | | payload.offers | [Offer](https://docs.recruitee.com/docs/webhooks#offer)\[] | Offers the deleted candidate was assigned to. | ## Job published Triggered when a new job is published. Example request body: ```json { "attempt_count": 1, "created_at": "2022-03-03T20:25:33.995135Z", "event_subtype": "manual", "event_type": "offer_published", "id": 75, "payload": { "company": { "id": 1, "name": "Devtest Company" }, "offer": { "created_at": "2020-10-22T17:45:00Z", "department": { "id": 123, "name": "Marketing" }, "id": 123, "kind": "job", "locations": [ { "country_code": "DE", "full_address": "Germany, Saarland, Düsseldorf, 90910, Saarlander Street", "id": 8, "state_code": "SL" }, { "country_code": "PL", "full_address": "Poland, Wielkopolskie, Poznań, 61-248, Polish Street", "id": 63, "state_code": "WP" } ], "slug": "front-end-web-developer", "tags": [ { "id": 123, "name": "Important" }, { "id": 123, "name": "Hiring Forecast Q3" } ], "title": "Front-end Web Developer", "updated_at": "2020-10-22T17:45:00Z" } } } ``` | Field | Type/format | Description | | :-------------- | :--------------------------------------------------------------- | :-------------------------------- | | event\_type | string | Always equals "offer\_published". | | event\_subtype | string | Always equals "manual". | | payload.company | [Company](https://docs.recruitee.com/docs/webhooks#simpleentity) | | | payload.offer | [Offer](https://docs.recruitee.com/docs/webhooks#offer) | Offer that has been published. | ## Job unpublished Triggered when a job is unpublished or archived. Example request body: ```json { "attempt_count": 1, "created_at": "2022-03-03T20:25:33.995135Z", "event_subtype": "manual", "event_type": "offer_unpublished", "id": 76, "payload": { "company": { "id": 1, "name": "Devtest Company" }, "offer": { "created_at": "2020-10-22T17:45:00Z", "department": { "id": 123, "name": "Marketing" }, "id": 123, "kind": "job", "locations": [ { "country_code": "DE", "full_address": "Germany, Saarland, Düsseldorf, 90910, Saarlander Street", "id": 8, "state_code": "SL" }, { "country_code": "PL", "full_address": "Poland, Wielkopolskie, Poznań, 61-248, Polish Street", "id": 63, "state_code": "WP" } ], "slug": "front-end-web-developer", "tags": [ { "id": 123, "name": "Important" }, { "id": 123, "name": "Hiring Forecast Q3" } ], "title": "Front-end Web Developer", "updated_at": "2020-10-22T17:45:00Z" } } } ``` | Field | Type/format | Description | | :-------------- | :--------------------------------------------------------------- | :------------------------------------------- | | event\_type | string | Always equals "offer\_unpublished". | | event\_subtype | string | Always equals "manual". | | payload.company | [Company](https://docs.recruitee.com/docs/webhooks#simpleentity) | | | payload.offer | [Offer](https://docs.recruitee.com/docs/webhooks#offer) | Offer that has been unpublished or archived. | ## Job updated Triggered when a job is updated. Example request body: ```json { "attempt_count": 1, "created_at": "2023-02-24T12:13:05.293345Z", "event_subtype": "offer_changed", "event_type": "offer_updated", "id": 77, "payload": { "company": { "id": 1, "name": "Devtest Company" }, "offer": { "created_at": "2022-04-19T10:28:01.492893Z", "department": { "id": 123, "name": "Marketing" }, "id": 123, "kind": "job", "locations": [ { "country_code": "DE", "full_address": "Germany, Saarland, Düsseldorf, 90910, Saarlander Street", "id": 8, "state_code": "SL" }, { "country_code": "PL", "full_address": "Poland, Wielkopolskie, Poznań, 61-248, Polish Street", "id": 63, "state_code": "WP" } ], "slug": "hr-manager", "status": "published", "tags": [ { "id": 123, "name": "Important" } ], "title": "HR Manager", "updated_at": "2023-02-24T12:13:05.205048Z" } } } ``` | Field | Type/format | Description | | :-------------- | :--------------------------------------------------------------- | :-------------------------------------------------------------- | | event\_type | string | Always equals "offer\_updated". | | event\_subtype | string | Can be "offer\_changed", "status\_changed", or "tags\_changed". | | payload.company | [Company](https://docs.recruitee.com/docs/webhooks#simpleentity) | | | payload.offer | [Offer](https://docs.recruitee.com/docs/webhooks#offer) | Offer that has been updated. | # Payload structure *** ## Candidate | Field | Type/format | Description | | :---------------- | :----------- | :------------------------------------------------------------------------ | | id | integer | | | name | string | | | emails | string\[] | | | phones | string\[] | | | photo\_thumb\_url | string | | | source | string | Can be one of "career\_site", "email", "manual", "import", or "referral". | | created\_at | ISO 8601 UTC | | | updated\_at | ISO 8601 UTC | | ## Offer | Field | Type/format | Description | | :---------- | :------------------------------------------------------------------ | :------------------------------------- | | id | integer | | | title | string | | | kind | string | Can be one of "job" or "talent\_pool". | | locations | [Location](https://docs.recruitee.com/docs/webhooks#location)\[] | | | slug | string | | | department | [Department](https://docs.recruitee.com/docs/webhooks#simpleentity) | | | tags | [Tag](https://docs.recruitee.com/docs/webhooks#simpleentity)\[] | | | created\_at | ISO 8601 UTC | | | updated\_at | ISO 8601 UTC | | ## PlacementLocations Locations attached to candidate's assignment to offer. A list of `Location`. ## CandidateMovedDetails The contents of `payload.details` in the "Pipeline change" event depend on `event_subtype`. There are three options. 1. `event_subtype` is "stage\_changed": | Field | Type/format | Description | | :---------- | :------------------------------------------------------ | :------------------------------------------ | | from\_stage | [Stage](https://docs.recruitee.com/docs/webhooks#stage) | Candidate's previous stage in the pipeline. | | to\_stage | [Stage](https://docs.recruitee.com/docs/webhooks#stage) | Candidate's new stage in the pipeline. | 2. `event_subtype` is "disqualified": | Field | Type/format | Description | | :----------------- | :------------------------------------------------------------------------ | :--------------------------------------- | | to\_stage | [Stage](https://docs.recruitee.com/docs/webhooks#stage) | The stage candidate was disqualified in. | | disqualify\_reason | [DisqualifyReason](https://docs.recruitee.com/docs/webhooks#simpleentity) | Reason for candidate's disqualification. | 3. `event_subtype` is "requalified": | Field | Type/format | Description | | :-------- | :------------------------------------------------------ | :--------------------------------------- | | to\_stage | [Stage](https://docs.recruitee.com/docs/webhooks#stage) | The stage candidate was brought back to. | ## SimpleEntity Includes `Company`, `Tag`, `Department`, `DisqualifyReason`. | Field | Type/format | Description | | :---- | :---------- | :------------- | | id | integer | Entity's ID. | | name | string | Entity's name. | ## Stage {`
Field Type/format Description

id

integer

Stage's ID.

name

string

Stage's name.

category

string

Stage's category. Can be one of "none", "apply", "phone_screen",
"interview", "evaluation", "offer", "hire".
`} ## Location | Field | Type/format | Description | | :------------ | :---------- | :----------------------------------------------------------------------------------- | | id | integer | Location's ID. | | country\_code | string | Locations' ISO 3166 country code | | state\_code | string | Locations' ISO 3166 state code | | full\_address | string | Concatenated values of location's country name, state, city, postal code and street. | # Email notifications *** Under [Settings > Apps and Plugins > Webhooks](https://app.recruitee.com/#/settings/webhooks/overview) you can choose team members that should be notified about failed webhook request deliveries. ![](https://files.readme.io/e998301-Screenshot_2020-12-14_at_06.29.46.png "Screenshot 2020-12-14 at 06.29.46.png")