Docs · API · Webhooks

Webhooks.

Get pushed the moment a run finishes or an application lands instead of polling for it. Deliveries follow the Standard Webhooks spec — the same signing scheme used by OpenAI, Anthropic, and Svix — so existing verifier libraries work unchanged.

Register an endpoint#

POST/v1/webhooks

Field	Type		Description
url	string (url)	required	Where events are POSTed. Must be https in production.
events	WebhookEvent[]	default: all four	Any of `job.succeeded`, `job.failed`, `application.received`, `screening.completed`.

Request

curl -X POST https://hire.whizztech.ai/v1/webhooks \
  -H "Authorization: Bearer $HIRE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://api.your-app.com/hooks/hire",
    "events": ["job.succeeded", "job.failed", "application.received", "screening.completed"]
  }'

Response · 201 Created

{
  "id": "a4f81c2d-6e93-40b7-95d2-3c08e7b1f649",
  "object": "webhook_endpoint",
  "url": "https://api.your-app.com/hooks/hire",
  "events": ["job.succeeded", "job.failed", "application.received", "screening.completed"],
  "secret": "whsec_Zks3JprXcO1FaK9yTqR2v8wBnE5dLmHu"
}

Secret — shown onceThe whsec_ signing secret appears only in this creation response. Store it next to your API key; you need it to verify every delivery. Listing endpoints later does not return it.

GET/v1/webhooks

Response · 200 OK

{
  "object": "list",
  "data": [
    {
      "id": "a4f81c2d-6e93-40b7-95d2-3c08e7b1f649",
      "url": "https://api.your-app.com/hooks/hire",
      "events": ["job.succeeded", "job.failed", "application.received", "screening.completed"],
      "active": true,
      "created_at": "2026-07-10T10:02:31.000Z"
    }
  ]
}

Endpoints are managed (deactivated, inspected, deliveries reviewed) at Dashboard → Webhooks. Inactive endpoints receive nothing.

Event catalog#

Field	Type	Description
job.succeeded	event	Any background run (jd_generate, screen_batch, interview_kit, distribute) finished successfully. data carries the run payload including result.
job.failed	event	A run failed. data.error explains; charged credits were refunded before this event fired.
application.received	event	A candidate applied through the career page, embed, or apply API. data carries application_id, job_post_id, candidate_id, and source.
screening.completed	event	A screening finished and ranked results are available. data carries screening_id and job_post_id — fetch GET /v1/screenings/{id}?include=results.

The body is { event, data }. For run events, data is the run payload minus the stages detail:

Delivery

POST /hooks/hire HTTP/1.1
Content-Type: application/json
webhook-id: 7c2f4e91-0b5d-4a68-93e1-d8f60a2c47b5
webhook-timestamp: 1783677103
webhook-signature: v1,K6mQxNvB2rTz8wYpL0dHc4jFgS7aEuXiOn9kM3sRq1U=

{
  "event": "job.succeeded",
  "data": {
    "id": "5b8f0d21-6a3e-4c97-b1d0-84e7f2a9c655",
    "type": "screen_batch",
    "status": "succeeded",
    "result": {
      "screening_id": "8a1c5e72-3f90-4b6d-a2e8-51c7d0b94f36",
      "screened": 87
    },
    "error": null,
    "credits_charged": 87,
    "created_at": "2026-07-10T10:05:12.000Z",
    "finished_at": "2026-07-10T10:12:44.000Z"
  }
}

Delivery semantics#

Events go to every active endpoint subscribed to that event type.
Your endpoint has 10 seconds to respond. Any 2xx counts as delivered; anything else — or a timeout — records the delivery as failed with the status code and error.
Three attempts per event. A failed delivery retries after ~30 seconds, then again after ~5 minutes; after the third failure it is marked dead. A retried delivery re-signs with a fresh webhook-timestamp. Still treat polling as the source of truth: on any gap, re-fetch GET /v1/runs/{id}. Delivery history is visible in the dashboard.
Ack fast: return 200 immediately and process the event on a queue. Slow handlers are the top cause of missed deliveries.
Deliveries can arrive out of order relative to your own API reads — always key your logic off data.id and data.status, not arrival order.

Signature verification#

Every delivery carries three headers:

Field	Type	Description
webhook-id	string	Unique delivery ID. Also your idempotency key for deduping.
webhook-timestamp	string	Unix seconds when the delivery was signed.
webhook-signature	string	`v1,<base64 MAC>` — HMAC-SHA256 over the signed content.

The scheme, exactly:

Key: strip the whsec_ prefix from your secret and base64-decode the remainder. The decoded bytes are the HMAC key — do not use the secret string directly.
Signed content: the string {webhook-id}.{webhook-timestamp}.{raw body} — the three values joined with periods, using the raw request body exactly as received.
Signature: "v1," + base64(HMAC-SHA256(key, signed content)). Compare against the header in constant time, and reject timestamps outside a small tolerance window (5 minutes is standard) to block replays.

Node#

verify.mjs

import { createHmac, timingSafeEqual } from "node:crypto";

/**
 * Verify a Whizz Hire webhook (Standard Webhooks scheme).
 * payload must be the RAW request body string — not re-serialized JSON.
 */
export function verifyHireWebhook(payload, headers, secret, toleranceSec = 300) {
  const id = headers["webhook-id"];
  const timestamp = headers["webhook-timestamp"];
  const signature = headers["webhook-signature"];
  if (!id || !timestamp || !signature) return false;

  // reject stale or future-dated deliveries (replay protection)
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > toleranceSec) return false;

  // key = base64-decoded secret without the whsec_ prefix
  const key = Buffer.from(secret.replace(/^whsec_/, ""), "base64");
  const signedContent = id + "." + timestamp + "." + payload;
  const expected =
    "v1," + createHmac("sha256", key).update(signedContent).digest("base64");

  // the header may carry multiple space-delimited signatures; ours sends one
  return signature.split(" ").some((candidate) => {
    const a = Buffer.from(candidate);
    const b = Buffer.from(expected);
    return a.length === b.length && timingSafeEqual(a, b);
  });
}

// Express example — mount with express.raw() so the body stays untouched:
// app.post("/hooks/hire", express.raw({ type: "application/json" }), (req, res) => {
//   if (!verifyHireWebhook(req.body.toString("utf8"), req.headers, process.env.HIRE_WEBHOOK_SECRET)) {
//     return res.status(401).end();
//   }
//   const { event, data } = JSON.parse(req.body.toString("utf8"));
//   res.status(200).end(); // ack fast, process async
// });

Python#

verify.py

import base64
import hashlib
import hmac
import time


def verify_hire_webhook(payload: bytes, headers: dict, secret: str, tolerance_sec: int = 300) -> bool:
    """payload must be the RAW request body bytes — not re-serialized JSON."""
    wid = headers.get("webhook-id")
    ts = headers.get("webhook-timestamp")
    sig = headers.get("webhook-signature")
    if not (wid and ts and sig):
        return False

    # reject stale or future-dated deliveries (replay protection)
    if abs(time.time() - int(ts)) > tolerance_sec:
        return False

    # key = base64-decoded secret without the whsec_ prefix
    key = base64.b64decode(secret.removeprefix("whsec_"))
    signed_content = f"{wid}.{ts}.".encode() + payload
    digest = hmac.new(key, signed_content, hashlib.sha256).digest()
    expected = "v1," + base64.b64encode(digest).decode()

    # the header may carry multiple space-delimited signatures; ours sends one
    return any(hmac.compare_digest(candidate, expected) for candidate in sig.split(" "))

The SDK exports this exact check as verifyWebhookSignature(payload, headers, secret) — Web Crypto based, so it runs in Node 18+ and edge runtimes.

NextUsage→