Hires API Overview

This API enables you to be notified when a candidate is hired on Recruit. This allows you to create a new employee record in an HRIS or talent management system and start the onboarding process for every new hire.

Getting started

• Recruit customers – this integration is available to Recruit customers on the Enterprise plan. To get started, follow the instructions in this API documentation to build your integration. When the integration is ready, you can enable it on the Integrations settings page.
• Integration partners – to partner with Recruit please contact us at [email protected].

Integration overview

The integration includes two webhooks. Recruit will make POST requests to the endpoints that you provide for each one of these webhooks:

1. Request hire questionnaire (optional) – Recruit makes a request to this webhook when a recruiter changes the status of a candidate to hired, before the Hire form is shown to the recruiter. This allows you to customize the hire form by adding additional fields to it. This is useful if you need to require the recruiter to provide details that are not managed in Recruit but are required for creating the new employee profile. Using this webhook is optional.

2. Create an employee – After the recruiter fills out the hire form, a request is made to this endpoint to create the new employee.

📘

Supporting multiple companies

If you plan to support multiple companies using Recruit, make sure to provide the customer with URLs that include a unique identifier of the company.

Configuring the integration in Recruit

A user with Admin, Owner or IT Manager role can enable this integration in Recruit on the Integrations page.

When enabling the integration, the following values should be defined:

• Request hire questionnaire (endpoint URL) – using this webhook is optional
• Create an employee (endpoint URL) – this webhook is required
• Secret Key – this key is used to generate a digital signature for verification, see details below

Verifying requests

All API calls use HTTPS and should be verified by your server.

1. To verify a request you need the Secret Key that was specified when setting up the integration in Recruit.
2. Recruit will add the signature header to the HTTP request.
3. Verify the request by generating a digital signature using the the SHA256 algorithm on the payload of the request with the Secret Key that was specified. The result must be identical to the signature header. You can use one of the many JWT libraries available online. If the values are not the same then fail the request with an unauthorized response (HTTP 401).

SECRET_KEY = 'XXXX'  # the key that was specified on the integration page in Comeet
request_signature_header_value = request.META['HTTP_SIGNATURE']  # the signature sent with the request
request_payload = request.body  # the payload sent in the request

# generate the signature value:
import hmac
import hashlib
alg = hashlib.sha256
local_signature_value = hmac.new(SECRET_KEY, msg=request_payload, digestmod=alg).hexdigest()
full_local_vlaue = "sha256 {}".format(local_signature_value)

# now, compare values:
if (full_local_vlaue == request_signature_header_value):
      # we are good to go
      ...
else:
     # not the same signature, HTTP 401 response is expected and the process should be stopped
     ...

/* Assuming payload is the request paylod: */
const data = JSON.stringify(payload);

const secretKey = 'XXXX'; // Replace with your actual secret key
const alg = 'sha256';

const crypto = require('crypto');

const hmac = crypto.createHmac(alg, secretKey);
hmac.update(data);

const sig = hmac.digest('hex');
const full_local_value = 'sha256 ' + sig; // This is the value to company with 'signature' HTTP header

/* 
In some cases option #1 will not work well and the payload json should be sorted.
In this case comparison with HTTP header signature-2 is required 
*/
function orderedJsonStringify(obj) {
  if (typeof obj !== 'object' || obj === null) {
    return JSON.stringify(obj); // For non-objects, use default JSON.stringify
  }

  if (Array.isArray(obj)) {
    // For arrays, recursively process each element
    return `[${obj.map(orderedJsonStringify).join(',')}]`;
  }

  // For objects, sort the keys and recursively process each key-value pair
  const sortedKeys = Object.keys(obj).sort();
  const sortedObject = {};
  for (const key of sortedKeys) {
    sortedObject[key] = orderedJsonStringify(obj[key]);
  }
  return `{${sortedKeys.map(key => `"${key}":${sortedObject[key]}`).join(',')}}`;
}

/* Assuming payload is the request paylod: */
const data = orderedJsonStringify(payload);

const secretKey = 'XXXX'; // Replace with your actual secret key
const alg = 'sha256';

const crypto = require('crypto');

const hmac = crypto.createHmac(alg, secretKey);
hmac.update(data);

const sig = hmac.digest('hex');
const full_local_value = 'sha256 ' + sig; // This is the value to company with 'signature-2' HTTP header