Webhooks

1. Expose a public https URL that accepts POST with a JSON body.
2. Register it in Organisation console → Developers → Webhooks, or with POST /api/v1/webhooks (scope webhooks:manage). Choose the events you want; the default is all of them.
3. Store the whsec_… signing secret you get back. It is encrypted at rest and shown only once.
4. Click Send test (or POST /api/v1/webhooks/{id}/test). A signed ping event arrives within a minute.

{
  "id": "9d0e4b7a-1c2f-4e5d-8a6b-7c9d0e1f2a3b",
  "type": "application.stage_changed",
  "created_at": "2026-10-24T10:15:02.123Z",
  "data": {
    "application_id": "3f6c2a9e-8b1d-4c7a-9e2f-5d4b1a0c7e91",
    "posting_id": "3f6c2a9e-8b1d-4c7a-9e2f-5d4b1a0c7e91",
    "from": "screening",
    "to": "interview"
  }
}

Payloads carry IDs and changed fields only, never names, emails, phone numbers or documents. Use event.id as an idempotency key and fetch details with your API key when you need them.

Compute HMAC-SHA256 over <t>.<raw body> with your secret and compare it in constant time with v1. Reject events whose t is more than 5 minutes from your clock, to stop replays. Always use the raw bytes: re-serialising parsed JSON changes them.

import express from "express";
import { verifyWebhook, WebhookVerificationError } from "@one-career/sdk/webhooks";

const app = express();
// keep the RAW body: the signature covers the exact bytes we sent
app.post("/oc-webhooks", express.raw({ type: "application/json" }), async (req, res) => {
  try {
    const event = await verifyWebhook({
      payload: req.body,
      header: req.get("OC-Signature"),
      secret: process.env.OC_WEBHOOK_SECRET!, // whsec_…
    });
    if (await seen(event.id)) return res.sendStatus(200);   // retries can repeat an event
    await queue.add(event);                                  // do the work later, answer fast
    res.sendStatus(200);
  } catch (e) {
    res.sendStatus(e instanceof WebhookVerificationError ? 400 : 500);
  }
});

// Any language: compute HMAC-SHA256 over "<t>.<raw body>" with your secret and compare in constant time.
import { createHmac, timingSafeEqual } from "node:crypto";

function verify(raw: Buffer, header: string, secret: string, toleranceSec = 300) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=") as [string, string]));
  const t = Number(parts.t);
  if (!t || Math.abs(Date.now() / 1000 - t) > toleranceSec) return false;      // replay window
  const expected = createHmac("sha256", secret).update(`${t}.`).update(raw).digest();
  const given = Buffer.from(parts.v1 ?? "", "hex");
  return given.length === expected.length && timingSafeEqual(given, expected);
}

import hmac, hashlib, time

def verify(raw: bytes, header: str, secret: str, tolerance: int = 300) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(","))
    t = int(parts.get("t", "0"))
    if abs(time.time() - t) > tolerance:
        return False
    expected = hmac.new(secret.encode(), f"{t}.".encode() + raw, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, parts.get("v1", ""))

• Answer with any 2xx within 10 seconds. Queue slow work and do it later.
• Anything else (non-2xx, timeout, network error, redirect) is retried after 1, 5, 30, 120, 360, 720 and 1440 minutes: 8 attempts over about a day. After that the delivery is marked dead.
• If an endpoint keeps failing for 3 days it is paused and your admins get a notification. Fix it and switch it back on in the console.
• Order isn't guaranteed and duplicates are possible. Use created_at and id.
• The console shows the last 25 deliveries with status code and error, so you can see what happened.