Candidate hired webhook
The Candidate Hired webhook fires an HTTP request to an external endpoint the moment a candidate’s status in Nextal changes to hired. This is the standard way to trigger downstream workflows — creating an employee record in an HRIS, onboarding in a third-party system, or updating a data warehouse — without manual data entry.
What it does
- Sends an HTTP POST to your endpoint when a candidate is marked as hired in Nextal.
- Supports five authentication modes: None, Basic Auth, Bearer Token, JWT, and API Key.
- By default, sends the complete candidate object. Optionally, enables custom field mapping to reshape the payload to match your endpoint’s expected schema.
- Accepts a Response ID Path so Nextal can extract and store the external system’s identifier from the response.
Prerequisites
- An HTTP endpoint (HTTPS strongly recommended) that can receive POST requests.
- Authentication credentials for that endpoint, depending on which auth mode it requires.
How to activate
- Go to Administration → Integrations and find the Candidate Hired Webhook card.
- Click Edit to open the configuration panel.
- Check Enable Candidate Hired Webhook.
- Enter the Webhook URL — the full HTTPS URL of your endpoint.
- Optionally, enter a Response ID Path — a JSON path expression (e.g.
$.data.id) pointing to the unique identifier in the endpoint’s response. - Choose an Authentication Type and fill in the corresponding fields (see Settings below).
- If your endpoint requires a specific payload structure, check Use Custom Field Mapping and map candidate fields to the JSON paths your endpoint expects. You can also add Custom Field entries to inject fixed values at arbitrary paths.
- Click Save.
Settings
Core settings
| Setting | Description |
|---|---|
| Enable Candidate Hired Webhook | Master toggle for the integration. |
| Webhook URL | The HTTPS endpoint that receives candidate data when a hire event fires. Required. |
| Response ID Path | A JSON path expression to extract the external system’s ID from the response (e.g. $.data.id). Optional. |
Authentication
| Authentication Type | Fields required |
|---|---|
| None | No credentials. |
| Basic Auth | Username and Password. |
| Bearer Token | Token value. |
| JWT | Algorithm (HS256 / HS384 / HS512 / RS256 / RS384 / RS512), JWT Secret, and optionally a JSON payload for token claims. |
| API Key | Key Name (e.g. X-API-Key), Key Value, and Location (Header or Query Parameter). |
Field mapping (optional)
When Use Custom Field Mapping is enabled, you can map standard candidate fields to the JSON paths your endpoint expects:
| Nextal field | Example target path |
|---|---|
| firstName | $.candidate.firstName |
| lastName | $.candidate.lastName |
$.candidate.email | |
| phone | $.candidate.phone |
You can also add Custom Fields to inject static values at any JSON path (for example, setting $.event to hired).
Tips
- Use HTTPS. Candidate payloads contain personal information — always use a secured, authenticated endpoint.
- Start without custom mapping. The default payload is the complete candidate object. Enable custom mapping only if your endpoint has a strict schema.
- Use the Response ID Path when creating records in an external HRIS. If the downstream system creates an employee record and returns its ID, storing that response ID in Nextal allows future updates to reference the correct record.
- This webhook fires once per hire event. If you need to update an already-hired candidate in the external system, that would require a separate mechanism.
- Test with a non-production candidate first. Create a test candidate, mark them hired, and verify the payload reaches your endpoint correctly before relying on this for live hires.