API Reference

Webhooks

Equalture ATS Webhooks Documentation

Overview

Webhooks in the Equalture ATS system are used to notify your application about two key events:

  1. When an assessment is started
  2. When an assessment is finished

Webhook Management

Endpoints

The API provides three main endpoints for webhook management:

  • PUT /connect_ats/webhooks - Create/Update webhooks
  • GET /connect_ats/webhooks - List existing webhooks
  • DELETE /connect_ats/webhooks - Remove webhooks

Authentication

All requests require Bearer token authentication. You need to Grant access token, which you can use for managing webhooks.

Implementation Flow

  1. Setting Up Webhooks

    • Use the PUT /connect_ats/webhooks/:label endpoint to register your webhook URL
    • Ensure your endpoint is publicly accessible
    • Your server should be configured to handle POST requests from Equalture

  2. Listing Webhooks

    • Use the GET endpoint to retrieve all configured webhooks
    • This helps verify your webhook configuration

  3. Updating Webhooks

    • Use the PUT /connect_ats/webhooks/:label endpoint to update your webhook URL

  4. Removing Webhooks

    • Use the DELETE endpoint when you need to stop receiving notifications
    • This completely removes the webhook configuration

Available webhooks

Your webhook endpoint will receive notifications for:

  • application_started: Triggered when a candidate begins an assessment
  • application_finished: Triggered when a candidate completes an assessment

Assessment Started Webhook

{
  "data": {
    "application_start_date": "2025-02-17T11:58:11",
    "reference_id": "306a6a69-fdc7-4b0b-a7a2-528df1aa316b"
  },
  "id": "a96b66b1-9a40-4911-9d93-b1ca664f0ba9",
  "type": "assessment_started"
}

Assessment Finished

{
  "data": {
    "reference_id": "ef955117-1ef3-4b08-b658-65da99f8a1b8"
  },
  "id": "c4b26ab9-1d6f-4142-bace-d4263cccd951",
  "type": "assessment_finished"
}

Security Implementation

Webhook Signature Validation

Following the Standard Webhooks specification, it's recommended to implement signature validation to ensure webhook authenticity and prevent tampering.

You may see, how signature is generated on: Verify signature

How Signature Validation Works

  • Each webhook request includes a signature in the Webhook-Signature header
  • The signature is created using a secret key shared between Equalture and your server
  • Your server should validate this signature before processing the webhook.
  • Standard webhooks signatures are generated using HMAC with SHA-256. The signed content is composed by concatenating the id, timestamp and payload, separated by the full-stop character (.)

Testing locally

For local development, we recommend using a tool like: ngrok. This will allow you to send test requests to validate that your endpoint is working properly.