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 partners@comeet.co.

Integration overview

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

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.
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.

To verify a request you need the Secret Key that was specified when setting up the integration in Recruit.
Recruit will add the signature header to the HTTP request.
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. 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_value = "sha256 {}".format(local_signature_value)

# now, compare values:
if (full_local_value == 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 canonicalize(obj) {

  if (obj === null || typeof obj !== 'object') {
    // Primitives (string, number, boolean, null) – leave as-is
    return obj;
  }

  if (Array.isArray(obj)) {
    // Arrays keep their original order; recursively canonicalize elements
    return obj.map(canonicalize);
  }

  // Objects: sort keys and recursively canonicalize values
  const sorted = {};
  Object.keys(obj).sort().forEach((key) => {
    sorted[key] = canonicalize(obj[key]);
  });
  return sorted;
}

function orderedJsonStringify(obj) {
  const canonical = canonicalize(obj);

  // Let JSON.stringify do the encoding/escaping and compact formatting
  return JSON.stringify(canonical);
}

/* 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