Skip to content

API

Webhooks.

We POST an event to your endpoint when an invitation is created, opened, resent, revoked or expires, an interview starts or finishes, results are ready or failed, your team decides, or a candidate is erased.

Last updated 19 November 2026

Add an endpoint

  1. Open Integrations → Webhooks and press Add endpoint (company admins; one endpoint on the free trial).
  2. Enter an https URL on the public internet (private and internal addresses are refused) and pick its events.
  3. Copy the signing secret (whsec_…). It stays on the endpoint's page, where you can also rotate it: for 24 hours after a rotation every delivery is signed with the new and the old secret (two v1 values), so you have a day to deploy the new one.
  4. Send a test event from the endpoint's menu: a test.ping arrives, signed like every other event. Its id starts with test_ and its data is { "webhookId": "<the endpoint's id>" }.

A company can have up to 20 endpoints; delete one you no longer use to add another.

Your systems can manage endpoints too, with an API key that has webhooks:manage: GET and POST /v1/webhooks, and GET, PATCH (edit, or active: false to pause and true to resume) and DELETE /v1/webhooks/{id}, POST /v1/webhooks/{id}/rotate-secret and POST /v1/webhooks/{id}/test. Creating one answers its signing secret, as the dashboard shows it; send an Idempotency-Key so a retry makes no second endpoint. The API reference has the fields.

Refused withWhen
400 Webhook URLs must use https.The URL isn't https
400 Webhook URLs must not contain credentials.It has a user name or password in it
400 Webhook host does not resolve.Its host name has no address
400 Webhook URLs must point to a public address.It resolves to a private, internal or loopback address
400 Validation failed.It isn't a URL, or is longer than 2,000 characters (issues names the field)
409 A company can have at most 20 webhook endpoints. Delete one you no longer use first.The company has 20 already

The address is checked again before every attempt (a DNS lookup, then a connection only to the address that passed), so a host that later points at a private address gets no requests.

Events

TypeWhen
invitation.createdAn invitation was created (dashboard, API or ATS)
invitation.openedThe candidate opened their link
invitation.resentThe invitation was sent again with a new link (the old ones stop working); an expired or revoked one is open again
invitation.revokedThe invitation was revoked before the candidate started: its links stop working and it reads as expired
invitation.expiredIts deadline passed before the candidate started (a resend opens it again with invitation.resent)
session.startedThe candidate started the interview
session.completedThe interview ended
results.readyThe analysis finished: fetch the results. data.partial is true when some blocks couldn't be analyzed (their status is error) and the score covers only the others; when a retry completes them, a second results.ready with partial: false and a new id follows, so key the final result on sessionId
results.failedThe analysis failed even after our automatic retries: the results' analysisStatus is error. Your team can retry it from the results page; if that succeeds, results.ready follows
review.decision_changedYour team changed its decision on the session in the dashboard: data.decision is the new one (undecided, advance, hold or reject)
candidate.erasedThe candidate and all their data were erased (a data-subject request, or your retention period ran out). data has only candidateId: delete your own copy of the candidate, their invitations and results

Team members' test runs of an interview (previews) never send events.

The payload

Payloads are thin: ids only, never names, emails or scores (results.ready adds partial, review.decision_changed the new decision). Fetch what you need with the API, so you always read current data and a leaked payload exposes nothing. externalId is the one you gave when inviting.

Every type's exact shape is WebhookPayload in the OpenAPI document (components.schemas), so you can generate its types. An event's id is an opaque string such as mi4k2x0a-7f3k9q2c: compare it, don't parse it.

POST your endpoint
{  "id": "mi4k2x0a-7f3k9q2c",  "type": "results.ready",  "timestamp": "2026-11-12T14:33:02.000Z",  "data": {    "invitationId": "inv_mh3m8k1qz8x4pd",    "candidateId": "cand_4f1b9c0e7a2d5e8f3b6c9a1d0e4f",    "interviewId": "iv_mh3k2p9x4f7a2c",    "sessionId": "Qx7vT2mKpL9nWb4sYc1e",    "externalId": "req-2291",    "partial": false  }}
HeaderValue
X-Testee-EventThe event type
X-Testee-DeliveryThe delivery's id, <endpoint id>--<event id>, the same on every retry
X-Testee-Signaturet=<unix seconds>,v1=<hex HMAC-SHA256>
Content-Typeapplication/json

Verify the signature

v1 is the HMAC-SHA256, keyed with your signing secret, of the timestamp t, a full stop and the raw request body. Compute it over the body exactly as received (before any JSON parsing), compare in constant time, and reject timestamps more than 5 minutes off so a captured request can't be replayed. The header can carry more than one v1 (after a rotation, below): accept the request when any of them matches.

import { createHmac, timingSafeEqual } from "node:crypto";
/** header: the X-Testee-Signature value; rawBody: the request body exactly as received. True when any v1 matches. */export function verifySignature(secret, rawBody, header, toleranceSec = 300) {  const pairs = (header ?? "").split(",").map((p) => p.split("="));  const t = Number(pairs.find(([k]) => k === "t")?.[1]);
  if (!t || Math.abs(Date.now() / 1000 - t) > toleranceSec) return false;  const expected = Buffer.from(createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex"));
  return pairs.some(([k, v]) => k === "v1" && v?.length === expected.length && timingSafeEqual(expected, Buffer.from(v)));}
  • Express: read the body raw on the webhook route, app.post("/webhooks/testee", express.raw({ type: "application/json" }), handler), and pass req.body (a Buffer) as rawBody; express.json() would hand you a re-serialized object whose signature no longer matches.
  • FastAPI: raw_body = await request.body() before any parsing, then json.loads(raw_body) once it's verified.
  • By hand: printf '%s.%s' "$T" "$BODY" | openssl dgst -sha256 -hmac "$SECRET" prints the v1 to expect for a timestamp T and a body BODY.

Responses and retries

  • Answer 2xx within 10 seconds. Anything else (a timeout, a redirect, any other status) counts as a failure. Do slow work after you answer.
  • Retries back off from 30 seconds to 8 hours, with some jitter, for about 24 hours. Then the delivery is marked failed. Answer 429 or 503 with Retry-After (seconds or a date) and the next attempt waits at least that long, up to 8 hours.
  • A few at a time. We send each endpoint only a few requests at once (at most 5 from each of our servers), so a bulk import of candidates arrives as a steady stream, not hundreds of requests at the same moment.
  • At least once. One event is delivered once per endpoint, but a retry can arrive after you processed it: skip a payload id you've already handled. A new event about the same thing has a new id (a second results.ready after a partial one, a decision changed again): key what you store on the session or invitation id.
  • Order isn't guaranteed. Events travel and retry separately, so results.ready can arrive before session.completed, and a retry can arrive after a later event. Order them by timestamp, or read the current state from the API.
  • Failing endpoints are turned off. When every delivery to an endpoint has failed for 5 days (at least 20 attempts in a row), it's paused (Integrations → Webhooks shows it). Fix it, then resume it: the count starts over, and the events of the pause are sent then (up to 30 days of them), so nothing is lost; the same goes for an endpoint you pause yourself.
  • Delivery log. Each endpoint's page lists its deliveries, filtered by status and event, with Replay to send one again (same payload and id). A failed attempt shows the status and the first 1 KB your endpoint answered, so an error message you return helps you find the cause.