Skip to main content
VirtualInterview.ai
Docs menu

Webhooks

A webhook sends a signed JSON POST to your HTTPS endpoint when a hiring event happens, such as an interview completing or an offer being accepted. Subscribe in the portal or through the API, verify each delivery with your signing secret, and answer with a 2xx status. Failed deliveries are retried.

Reference · Last checked against the product on

Subscribe to events

In the portal:

  1. Open Settings → Developers, and in the Webhooks card click New endpoint.
  2. Enter the HTTPS URL that will receive deliveries.
  3. Tick the Events you want, then click Add endpoint.
  4. The Webhook created dialog shows the signing secret once. Copy it into your receiver’s configuration.

Or register through the API with a webhooks:write key. Pass your own secret (at least sixteen characters) or leave it out; a generated one is returned once, in the response.

Shell
curl -X POST https://hiring.virtualinterview.ai/api/v1/hiring/webhooks \
  -H "Authorization: Bearer $VI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://example.com/webhooks/hiring", "events": ["invitation.completed", "offer.accepted"] }'

The URL must use HTTPS on the standard port and resolve to a public address. It is checked when you register it and again before each delivery, and redirects are not followed. The Webhooks card states how many endpoints an organisation can have.

Events

Webhook events
EventGroup
invitation.createdinvitation
invitation.completedinvitation
invitation.expiredinvitation
candidate.stage_changedcandidate
candidate.decision_madecandidate
offer.sentoffer
offer.acceptedoffer
offer.declinedoffer
onboarding.startedonboarding
application.openedapplication
application.stage_changedapplication
agent.run.completedagent
recommendation.createdrecommendation
scorecard.submittedscorecard
interview.scheduledinterview
offer.approvedoffer

Three older names are still accepted when you subscribe and are stored as the event that fires: candidate.invited becomes invitation.created, and both candidate.completed and interview.scored become invitation.completed. The interview score arrives on invitation.completed.

Payload and headers

Every delivery is a POST with a JSON body. data always carries the job title and the candidate’s email and name, the job id when there is one, and fields specific to the event.

Body
{
  "event": "invitation.completed",
  "timestamp": "2026-11-14T09:30:00.000Z",
  "data": {
    "jobTitle": "Backend Engineer",
    "candidateEmail": "sam@example.com",
    "candidateName": "Sam Lee",
    "jobId": "cm2…",
    "…": "event-specific fields"
  }
}
Delivery headers
HeaderValue
X-Webhook-EventThe event name.
X-Webhook-TimestampThe same value as timestamp in the body.
X-Webhook-DeliveryThe delivery id. It stays the same across retries, so use it to ignore duplicates.
X-Webhook-AttemptWhich attempt this is, starting at 1.
X-Webhook-Signature-V2Hex HMAC-SHA256 of {timestamp}.{body} with your signing secret. Verify this one.
X-Webhook-SignatureHex HMAC-SHA256 of the body alone. Kept for receivers built before the V2 header.

Verify a delivery

Compute the HMAC over the raw body exactly as received. Parsing and re-serialising the JSON changes the bytes and the signature will not match. Compare in constant time, and refuse old timestamps.

Node.js
import crypto from 'node:crypto';

// rawBody: the request body exactly as received, before JSON parsing.
export function verifyDelivery(rawBody, headers, secret) {
  const timestamp = headers['x-webhook-timestamp'];
  const received = headers['x-webhook-signature-v2'];
  if (!timestamp || !received) return false;

  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${timestamp}.${rawBody}`)
    .digest('hex');

  const a = Buffer.from(received, 'hex');
  const b = Buffer.from(expected, 'hex');
  if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) return false;

  // Refuse old deliveries so a captured request cannot be replayed.
  const ageMs = Date.now() - Date.parse(timestamp);
  return ageMs < 5 * 60 * 1000;
}

Every delivery is signed. An endpoint without a signing secret receives nothing.

Retries and switching off

What happens to a delivery
Your endpoint answersResult
Any 2xxDelivered. The endpoint’s failure count goes back to zero.
5xx or 429Retried later, with longer waits between attempts, up to a fixed number of attempts.
A timeout or network errorRetried the same way.
Any other status, including a redirectNot retried.

Answer quickly and do the work afterwards: a delivery that takes too long is treated as a network error. The Failures column counts events in a row whose first attempt failed. When that run gets long enough the endpoint is switched off and the organisation’s owners and admins, and whoever created the endpoint, get a Webhook switched off notification. Fix the endpoint, then turn its Active switch back on; that resets the count.

Was this page clear?