Webhooks

Webhooks allow Comsalo to push real-time event notifications to your own server. Instead of polling the API, your backend receives an HTTP POST request the moment something happens — a candidate applies, an interview completes, and more.

Webhook configuration is coming soon. Register your interest by emailing [email protected]

Event types

candidate.created

A new candidate has applied or been added to your pipeline.

candidate.status_changed

A candidate's status changed (e.g. pending → in_progress).

interview.scheduled

An AI interview has been scheduled for a candidate.

interview.completed

A candidate has completed their interview. Scoring begins.

interview.scored

AI scoring is complete. Candidate report is available.

interview.no_show

Candidate did not attend the scheduled interview.

Payload structure

Every webhook event is delivered as an HTTP POST with a JSON body in the following shape:

Webhook payload

{
  "event": "interview.completed",
  "created_at": "2026-03-14T15:30:00.000Z",
  "data": {
    "interview_id": "c4d5e6f7-...",
    "candidate_id": "a1b2c3d4-...",
    "company_id":   "b2c3d4e5-...",
    "job_id":       "d3e4f5a6-...",
    "status":       "completed",
    "completed_at": "2026-03-14T15:28:44.000Z"
  }
}

Verifying webhook signatures

Each request includes a X-Comsalo-Signature header containing an HMAC-SHA256 signature of the raw request body. Use your webhook secret to verify authenticity.

verify-webhook.js

import crypto from 'crypto'

function verifyWebhook(rawBody, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(rawBody)
    .digest('hex')

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  )
}

Retries

If your endpoint returns a non-2xx status code, Comsalo will retry the event with exponential backoff — up to 5 attempts over 24 hours. Return 200 OK as soon as you receive the event, and process asynchronously.