Permissions: Site Admin who can manage ALL organization's API Credentials and manage and configure web hooks, and Job Admin who can manage ALL organization's API Credentials, manage and configure web hooks, manage custom fields, and create new job stage names

Product tier: Available for Advanced and Expert subscription tiers

SHL is the global leader in talent innovation, helping more than 10,000 companies transform productivity through deeper people insight. Powering the future of business, SHL's data and tools are proven to drive stronger, more sustainable business outcomes.

SHL's webhook integration with Greenhouse Recruiting provides recruiters and hiring managers with an easy way to assess candidates as part of the candidate workflow.

Note: The SHL webhook integration is only available for organizations with an Advanced or Expert Greenhouse subscription.

Overview

With the SHL webhook integration, a recruiter can manually trigger a specific assessment for a candidate. SHL will send an email to the candidate to complete the assessment, and when complete, Greenhouse Recruiting will share the assessment results on the candidate's Details tab.

Note: There is a separate SHL integration called SHL (TalentCentral) integration that will automatically launch an assessment as soon as an application is submitted, or at a specific step in the interview plan in Greenhouse Recruiting. The candidate will receive an email after applying or as soon as a recruiter moves them to a specific stage. Your organization can decide which of the two SHL integrations works best for your hiring processes.

Enable the SHL webhook integration

Create a Harvest API key

To enable the Greenhouse Recruiting / SHL integration, you'll need to create a Harvest API key.

Follow the steps in this article to create the key, and verify that the credentials and permissions below are selected.

Credentials

In the Create New Credential box, make the following selections:

  • API Type: Harvest
  • Partner: SHL
  • Description: SHL Harvest API key

Permissions

Verify that the following permissions are selected for the integration:

Applications

  • All permissions

Custom fields

  • GET: Get custom fields

Job stages

  • GET: List job stages for job

Jobs

  • GET: Retrieve job

When finished, click Save.

Your Harvest API key for the SHL integration is created and configured. Provide the Harvest API key to your SHL representative.

Retrieve your Greenhouse Recruiting user ID

In order to provide updates directly in Greenhouse Recruiting, SHL requires the user ID of a Greenhouse Recruiting user to associate with integration updates.

You can create an integration system user (ISU) in Greenhouse Recruiting specifically for SHL, or you can share an existing person's user ID.

Using either method, follow the steps in this article to retrieve a user ID and share it with the SHL team.

Create a webhook

Note: Before configuring the integration's webhook, make sure you've received your organization's unique endpoint URL from SHL.

To integrate SHL with Greenhouse Recruiting, you'll need to create a webhook. Follow the steps in this article to create your webhook. Use the values listed below.

  • Name: SHL integration
  • When: Candidate has changed stage
  • Endpoint URL: The unique endpoint URL received from SHL
  • Secret key: Enter any string of characters, such as greenhouse secret key. The secret key must be shared with the SHL team after creating the webhook.

When finished, click Create Web hook.

Create custom fields

The SHL integration requires several custom job and application fields in Greenhouse Recruiting.

Custom job field

Follow the steps in this article to create a custom job field, and use the following details when configuring the field:

  • Field Name: shl_assessment_tag
  • Field Type: Short textbox
  • Create new email token: Yes
  • Required: Yes

Note: Be sure the field's exact name is shl_assessment_tag. This field will retain the external package tag value from SHL to be assigned to candidates for that job.

When finished, click Save.

Custom application fields

Next, follow the steps in this article to create six (6) custom application fields, using the following details:

Field Name Field Type Where should this field show up? Create new email token Mark Private Additional details
shl_assessment_tag Short textbox Candidate Yes Yes This field that holds the assessment / IC external package tag. It's possible to have multiple package tags.
shl_candidate_url Short textbox Candidate Yes Yes This field is not directly used by Greenhouse Recruiting, but is informative to the recruiter, for example if a candidate misplaces the email assessment invitation.
shl_overall_status Short textbox Candidate Yes Yes This field is not directly used by Greenhouse Recruiting but is informative to the recruiter to identify an issue, or to assist SHL in troubleshooting if necessary.
shl_reports_url Short textbox Candidate Yes Yes SHL provides the URL to access the link in candidate reports.
shl_ignore (Optional)         Some clients choose to configure this field so that during bulk or automatic operations they have a way to indicate that a particular application should be ignored. If the value is set to true or 1, then the notification is ignored.
SCORES Short textbox Candidate Yes Yes For each score that needs to be returned, a custom field with the same value needs to be created. For example, if you want to return a score called overall_score (or the client friendly name as configured by SHL) then such a custom field needs to be configured within Greenhouse Recruiting.

Add SHL stages to an interview plan

Finally, you're ready to add the SHL stages to a job's interview plan in Greenhouse Recruiting.

Navigate to an existing job (Jobs > Job name), or create a new job.

Click the Job Setup tab, and then click Interview Plan.

Click Add stage.

Click the Create New Stage field and type Send SHL Assessment for the name.

The Create New Stage fields shows the text 'Send SHL asssessment' entered

Click Add.

Repeat this process to add three (3) additional SHL stages to your interview plan:

  • Pending SHL Assessment
  • Completed SHL Assessment
  • Error SHL Assessment

For more details on how the stages are used, check out the table below.

Stage name Purpose
Send SHL Assessment Candidates can be moved to the Send SHL Assessment stage by the recruiter to initiate an assessment manually. 
Pending SHL Assessment Once assessment registration is complete, SHL moves the candidate into the Pending SHL Assessment stage. This signifies the candidate has the link to take the assessment.
Completed SHL Assessment Once the candidate completes the assessment, the scores and reports are returned to Greenhouse Recruiting and the candidate is moved to the Completed SHL Assessment stage.
Error SHL Assessment If an issue occurs with the assessment invitation (such as a bad email address) SHL will move the candidate to the Error SHL Assessment stage.

Once you create these stages and add them to one job, the stages will be available to add on additional jobs where you wish to use the SHL integration.

(Optional) Test the SHL integration

If you wish to test the SHL integration before using it with a live candidate, you can add a test candidate to Greenhouse Recruiting and move the candidate into the Send SHL Assessment stage. Use a different, valid email address for the candidate than the email address you use to log into Greenhouse Recruiting.

Note: When you add the candidate to Greenhouse Recruiting, be sure you initially add them to a non-SHL stage. Once the candidate is added, you can manually move them into the Send SHL Assessment stage.

Use the SHL integration with Greenhouse Recruiting

When a candidate is moved into the Send SHL Assessment stage, SHL will trigger an assessment and email the candidate a link to complete it.

The candidate will automatically be moved into the Pending SHL Assessment stage once they receive the link.

When the candidate completes their assessment, the scores and reports will be returned to Greenhouse Recruiting and the candidate can be moved to the Completed SHL Assessment stage.