Workday Recruiting Integration - Setting up interview orchestration setup

Overview

imper.ai integrates with Workday Recruiting to receive real-time notifications when candidates enter and exit the Interview stage. This allows imper.ai to activate candidate identity protection exactly when it is needed — during interviews — and deactivate it automatically once interviews conclude.

The integration is lightweight by design. Workday sends a minimal webhook payload at two points in the hiring process; imper.ai pulls any additional candidate data separately via the Workday API.

How it works

Two Workday Orchestrate actions are added to the Job Application Business Process — one before the first interview stage, and one after the last.

Hook	Trigger	Purpose
Pre-interview	Candidate enters the first Interview stage	Signals imper.ai that interviews are starting for this candidate
Post-interview	Candidate exits the last Interview stage	Signals imper.ai that interviews have concluded

Webhook specification

Both hooks send an HTTPS POST request to the imper.ai endpoint with a small JSON payload.

Endpoint

POST https://webhook‑relay.prod.imper.ai/webhooks/\<orgid\>/workday

Authentication

An API key is passed as a request header:

Authorization: Bearer <API_KEY>

The API key is provided by imper.ai and should be stored securely in Workday — for example, encrypted within the Orchestration's credential configuration.

Request payload

{
 "event_type": "interview_started" | "interview_ended",
  "candidate_id": "WD-12345",
  "job_application_id": "JA-67890",
  "job_requisition_id": "JR-11111",
  "timestamp": "2026-04-09T14:30:00Z"
}

Field	Type	Description
`event_type`	string	`interview_stage_started` for the pre-interview hook; `interview_stage_ended` for the post-interview hook
`candidate_id`	string	The Workday Candidate ID (WID)
`job_application_id`	string	The Workday Job Application ID
`job_requisition_id`	string	The Workday Job Requisition ID
`timestamp`	string (ISO 8601)	When the stage transition occurred

The payload is intentionally minimal. The candidate and application IDs are used to retrieve any additional data needed — candidate name, job profile, requisition details — via the Workday REST/SOAP API.

Expected response

Response	Meaning
`200 OK`	Webhook received successfully. The Orchestration step auto-completes and the business process continues.
`4xx / 5xx`	An error occurred. See Error Handling below.

Error handling

The Orchestration should be configured so that a failed webhook call does not block the business process.

If the imper.ai endpoint is unreachable or returns an error, the business process continues normally — recruiters are never blocked from moving candidates forward. Failed calls can be logged on the Workday side for retry or alerting.

Orchestration Setup Steps

Your Workday integration team will need to complete the following:

Go to: developer.workday.com
Navigate to apps and click on Create App.
Select Start from Scratch and create orchestration
Create a trigger: Use an event like Job Application business‑process event or Recruiting event.
Mapping step: Pull essential data fields: Candidate ID, Stage, Step, Status, etc.
Final step: Set an HTTP POST to your backend URL (Using “Send HTTP Request”): https://webhook‑relay.prod.imper.ai/webhooks/\<orgid\>.

Business Process Configuration

In the search bar, type "Job Application or Recruitment Business Process (BP)" and find the BP by its name.
Click Edit
1. (Optional) Trigger a specific state: To target a specific state within a stage (e.g., “Interview stage”), click the relevant step. Otherwise, select the stage itself.
2. Add Action (or type Orchestration): Add "Call Orchestration" (or "Business Process Action") or “Orchestration” type”.
Choose Orchestration: Select "ImperCandidateStateOrchestration".

Setup Steps - SOAP API

Workday Studio Setup

Go to Workday Studio (Maybe under "Installation").
Create a New integration and call it "ImperListener".
Create a new integration: Select "Web Service" or "Inbound" → "SOAP Web Service".
Set details:
1. Operation name: "TriggerCandidateStateChange"
2. Input type: "JobApplicationEventType"

Example XML Structure:

The XML payload should look similar to this:

<TriggerCandidateStateChange_Request xmlns="http://your-company.com/workday/webhooks">
  <Job_Application>
    <Job_Application_ID>WAPPLIC12345</Job_Application_ID>
    <Candidate_Reference>
      <ID type="Candidate_ID">W12345</ID>
    </Candidate_Reference>
    <Requisition_Reference>
      <ID type="Requisition_ID">REQ678</ID>
    </Requisition_Reference>
    <Stage>Interview</Stage>
    <Step>Phone Screen</Step>
    <Current_Status>Screening</Current_Status>
  </Job_Application>
</TriggerCandidateStateChange_Request>

Integration Configuration:

Store the SOAP endpoint URL: Workday provides this URL, which looks like:
"https://YOUR‑TENANT‑URL/workers/cloud/soap/.../CandidateStateChangeListener/TriggerCandidateStateChange"
Set HTTP post step:
Host: https://webhook-relay.imper.ai/webhooks/\<orgid\>/workday
Header: Content-Type: application/json
Add Data Transformation / mapping step (or allow Studio to auto‑map) for the following fields:
1. candidate_id
2. job_application_id
3. requisition_id
4. stage
5. step
6. status

Business Process Configuration:

Search for: "Job Application business process" or "Manage Job Application Business Process" or navigate to Open Recruiting → Recruiting Setup → look for "Job Application Business Process" or "Recruiting Business Processes".
Enter edit mode.
Select the trigger point:
1. To trigger for specific states within a stage (e.g., "Interview stage"), click on the relevant Step.
2. Otherwise, click on the Stage.
Add Action: Add "Call Web Service".
Point it to: The SOAP endpoint URL saved from Studio.
Input / Data section: Check or select fields to be sent, such as:
1. Job Application
2. Candidate
3. Stage
4. Step
5. Status (or Current_Status, depending on your tenant’s naming).