API Documentation

Webhooks

A webhook is a simple event-notification system. When an event occurs in HRPeak, a payload of JSON data containing information about the event is sent via POST to a specified endpoint URL over HTTPS.

Webhook Definition

A webhook can be defined with the following properties.

Nameoptional

Name of the webhook. The name is simply a reference for you. It can contain any string value.

Endpoint URL

The callback URL your application will use to accept the incoming webhook. This is the URL to which we will send the POST data when the event occurs.

Event Type

The event you want to listen. For example, candidate completed the assessment, candidate status was changed.

Additional Headersoptional

You can add custom HTTP header values when sending a POST request to your environment via webhook.

Webhook Security

HTTPS Endpoints

Since we are sending confidential candidate information outside of HRPeak via webhooks, we need to ensure all traffic is encrypted. For this reason, we only support HTTPS enabled endpoints.

Secret Key

This secret key will be used to generate a signature that you may use to verify the hook data was sent from HRPeak. HRPeak signs the hook data and includes token and the signature within the body of the POST request. A different token is added to each request. HMAC algorithm is used to generate the signature. (using your secret key as a key and SHA256 digest mode)

To compute the HMAC digest in C#:

using (var hmacsha256 = new HMACSHA256(Encoding.UTF8.GetBytes(secretKey)))
{
    var hash = hmacsha256.ComputeHash(Encoding.UTF8.GetBytes(token));
    var signature = String.Concat(hash.Select(c => c.ToString("x2")));
}

To compute the HMAC digest in NodeJS:

const crypto = require('crypto');

const signature = crypto
  .createHmac('sha256', Buffer.from(secretKey, 'utf8'))
  .update(Buffer.from(token, 'utf8'))
  .digest('hex');

To compute the HMAC digest in PHP:

$signature = hash_hmac('sha256', $token, $secret_key);

Webhook Payloads

The endpoint at the URL you specify in webhooks settings will receive POST requests containing JSON formatted data like the following:

event_id

Unique ID for this event.

event_type

The type of the event. Data type is integer.

Possible values

Value	Text
0	Candidate status changed or current status information is has been updated.
1	Candidate has used or fully completed the assessment.

event_subtypeJSON may not include this property.

The subtype of the event. Data type is integer.

Possible values

Value	Text
0	A new flow has begun for the candidate.Occurs only when webhook event type is 0.
1	The candidate's status has changed.Occurs only when webhook event type is 0.
2	The candidate's status has not changed, only the information in the current status has been updated.Occurs only when webhook event type is 0.
0	The candidate assessment report has been created. In some assessments, it is sufficient for the candidate to complete a part of the assessment for the report to be created.Occurs only when webhook event type is 1.
1	The candidate has completed the assessment.Occurs only when webhook event type is 1.

created_at

When webhook event was triggered. Data type is datetime.

token

Randomly generated string to generate signature.

signature

Signature generated using your secret key and then token value.

attempt_count

In the case of a failed webhook request, sending the payload to endpoint address is retried. attempt_count shows the number of retries. Data type is integer.

payload

Event specific data

Sample JSON

{
  "event_id": "mhnu8aq5bc4dyhbfm25rr54xda",
  "event_type": 0,
  "event_subtype": 3,
  "created_at": "2026-08-04T04:22:00Z",
  "token": "gjd28tucllxnwtlrt8syp7v6sa",
  "signature": "072d5ed699a7888785c9f29963a4d33058a47f552176c633f77d06893d14b923",
  "attempt_count": 1,
  "payload": {
    "tracking_number": "qhsvtc5amdbdy8v7t26fdwnkp3",
    "flow": {
      "id": "bbxd2v9uupa8wxc8hp373pkzsq",
      "name": "Flow 01"
    },
    "step": {
      "id": "u3getvlncrd7ykvpdvnlzx4pyx",
      "name": "Step 01",
      "type": 4
    },
    "status": {
      "id": "abt3shyjwlg3yjlctk5wmts66w",
      "name": "Hired",
      "code": "recruitment_hired"
    },
    "start_date": "2026-08-04T00:00:00+03:00",
    "date": "2026-07-29T09:51:00Z"
  }
}

{
  "event_id": "px5zxfl4jk9yyamm69a655sxpz",
  "event_type": 1,
  "event_subtype": 1,
  "created_at": "2026-08-04T04:22:00Z",
  "token": "gpcmjxzbkcyawunuravgzcgzb2",
  "signature": "226deb85b1539af0ef7a4b072a6ed496e9fcbab6f75a51fa8ada6f7bb9cf9e47",
  "attempt_count": 1,
  "payload": {
    "id": "uve25y3jd8lewbxaqb95fyurda",
    "tracking_number": "mqqq2zn8zhevy7mrwpg58j8sh3",
    "assessment_id": "crxjzp2asnysy7m7djv8g2wm6a",
    "assessment_type": 0,
    "assessment_name": "English Proficiency Test",
    "date": "2026-07-18T04:25:00Z",
    "score": 80,
    "level": "B1"
  }
}

Retry Policy

In the case of a failed webhook request (due to network issues, a non HTTP 200 response or timeout), HRPeak will retries up to 10 times with increasing intervals.

Retry Attemps	Retry Interval
First run	Less than 1 minute after the event
Retry 1	5 minutes after previous run
Retry 2	15 minutes after previous retry
Retry 3	30 minutes after previous retry
Retry 4	1 hour after previous retry
Retry 5	2 hours after previous retry
Retry 6	5 hours after previous retry
Retry 7	12 hours after previous retry
Retry 8	1 day after previous retry
Retry 9	2 days after previous retry

List Webhooks

Returns the list of all webhooks.

Request Information

GEThttps://api-test.hrpeak.com/v2/webhooks

The API uses basic authentication and the API key must be sent in the Authorization request header.

curl https://api-test.hrpeak.com/v2/webhooks
-H "Authorization: API_KEY"

URI parameters

active_items_onlyoptional

List only items with active status. Data type is boolean. Default value is true.

Response Information

Unique id of the webhook.

nameJSON may not include this property.

Name of the webhook.

event_type

The type of the event. Data type is integer.

Possible values

Value	Text
0	Candidate status changed or current status information is has been updated.
1	Candidate has used or fully completed the assessment.

endpoint

The URL where the callback should be sent.

status

Status of the webhook Data type is integer.

Possible values

Value	Text
0	Passive
1	Active
2	Paused

Sample Response

{
  "status": 0,
  "data": [
    {
      "id": "txkm4cjm8zljwucf5ltskhxauz",
      "event_type": 1,
      "endpoint": "https://hrpeak.requestcatcher.com/test",
      "status": 1
    }
  ]
}

Error Responses

Error messages can vary. More specific error information may be included.

Internal server error

{
  "status": 500,
  "error_message": "A generic error has occurred on the server."
}

List Webhook Events

List details about webhook events from the past 1 year.

Request Information

GEThttps://api-test.hrpeak.com/v2/webhooks/{id}/events

The API uses basic authentication and the API key must be sent in the Authorization request header.

curl https://api-test.hrpeak.com/v2/webhooks/{id}/events
-H "Authorization: API_KEY"

URI parameters

idrequired

Unique id of the webhook.

pageoptional

The zero-based page number. Data type is integer. Default value is 0.

per_pageoptional

The number of items per page. Maximum value is 1000. Data type is integer. Default value is 100.

start_dateoptional

Filter events with time interval. The time at which the event was occured. Data type is datetime.

end_dateoptional

Filter events with time interval. The time at which the event was occured. Data type is datetime.

Request Uri Sample

https://api-test.hrpeak.com/v2/webhooks/dd2wx8envje5yfnzexc7huv9qq/events/?page=0&per_page=20

Response Information

event_id

Unique ID for this event.

event_subtypeJSON may not include this property.

Sub type. Data type is integer.

Possible values

Value	Text
0	A new flow has begun for the candidate.Occurs only when webhook event type is 0.
1	The candidate's status has changed.Occurs only when webhook event type is 0.
2	The candidate's status has not changed, only the information in the current status has been updated.Occurs only when webhook event type is 0.
0	The candidate assessment report has been created. In some assessments, it is sufficient for the candidate to complete a part of the assessment for the report to be created.Occurs only when webhook event type is 1.
1	The candidate has completed the assessment.Occurs only when webhook event type is 1.

endpoint

The URL to which callback is sent.

payload

Event specific data

response

The response received from your server.

status

Status. Data type is integer.

Possible values

Value	Text
0	OpenThe webhook payload has not been delivered yet.
1	OKWebhook payload delivered successfully.
2	ErrorAn error occurred during the delivering of the webhook payload to the endpoint.

Sample Response

{
  "status": 0,
  "total_data_count": 1000,
  "data": [
    {
      "event_id": "fgsymfrgyencwgcbulpmqcgjz3",
      "endpoint": "https://hrpeak.requestcatcher.com/test",
      "payload": {
        "id": "hcw4xfe6umqswkx24axpjyp2pz",
        "tracking_number": "mp8keg4rfr2cwhbacfq9gw2q7q",
        "assessment_type": 0,
        "assessment_name": "English Proficiency Test",
        "date": "2026-07-15T23:20:00Z",
        "score": 80
      },
      "status": 1
    },
    {
      "event_id": "q9fsjgemss49ywmlxq6wjqrrhs",
      "endpoint": "https://hrpeak.requestcatcher.com/test",
      "payload": {
        "id": "emxzpkhg8v8by5bmjb3wjebtbz",
        "tracking_number": "xg5ph48ez79by8cla42adq3dl2",
        "assessment_type": 0,
        "assessment_name": "English Proficiency Test",
        "date": "2026-07-19T16:42:00Z",
        "score": 65
      },
      "status": 1
    }
  ]
}

Error Responses

Error messages can vary. More specific error information may be included.

Bad request

{
  "status": 400,
  "error_message": "Invalid request."
}

Internal server error

{
  "status": 500,
  "error_message": "A generic error has occurred on the server."
}