Hires API Overview

This API enables you to be notified when a candidate is hired on Comeet. 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

Comeet customers – this integration is available to Comeet 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 Comeet please contact us at [email protected].

Integration overview

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

Request hire questionnaire (optional, currently in beta) – Comeet 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 Comeet 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 Comeet, make sure to provide the customer with URLs that include a unique identifier of the company.

Configuring the integration in Comeet

A user with Admin, Owner or IT Manager role can enable this integration in Comeet 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 Comeet.
Comeet 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. 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
     ...