WorkHook API v1

Quick start

1. Log in as the employer, open Company profile → API & integrations and create a key. The API is included with every paid employer plan.
2. Send JSON to https://workhook.co.za/api/v1 with the header Authorization: Bearer whk_...
3. Post your first job:

curl -X POST https://workhook.co.za/api/v1/jobs \
  -H "Authorization: Bearer whk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "external_ref": "ATS-10442",
    "title": "Bookkeeper",
    "description": "<p>A growing accounting practice in Centurion needs a bookkeeper ...</p>",
    "category": "Accounting & Finance",
    "job_type": "Permanent",
    "work_mode": "On-site",
    "level": "NQF 6",
    "salary": {"min": 18000, "max": 24000, "currency": "ZAR", "period": "month"},
    "location": {"country": "ZA", "area": "Centurion"},
    "applicants_from": ["ZA"],
    "must_have": ["Pastel or Sage", "3 years bookkeeping"],
    "closing_date": "2026-12-15",
    "apply_email": "jobs@youragency.co.za"
  }'

The answer (HTTP 201) is the job with its WorkHook ref and public url. It is live straight away - send "publish": false to keep it as a draft.

{
  "ok": true,
  "data": {
    "ref": "kz99h22dbt",
    "external_ref": "ATS-10442",
    "url": "https://workhook.co.za/job.php?job=kz99h22dbt",
    "type": "job",
    "status": "Live",
    "title": "Bookkeeper",
    ...
  }
}

Keys, access and limits

• Authentication: Authorization: Bearer whk_... on every request. If your server strips that header, send X-Api-Key: whk_... instead.
• One key per system. Each key acts for one employer account. Revoke a key any time on the API page; the full key is only shown once when you create it.
• Who can use it: employers with an active paid plan (WorkHook can also switch it on for you). Publishing follows the same rules as the website - your plan's listing allowance, approval of new accounts and moderation.
• Rate limit: 60 requests a minute per key. Responses include X-RateLimit-Remaining; above the limit you get 429 with Retry-After.
• Format: JSON in (Content-Type: application/json), JSON out. Dates as YYYY-MM-DD, times in ISO 8601 (South African time, +02:00). Always use https.
• If your system cannot send PATCH or DELETE, send POST with X-HTTP-Method-Override: PATCH.

Errors

Every error has the same shape. fields is there when some fields need attention:

HTTP/1.1 422
{
  "ok": false,
  "error": {
    "code": "validation",
    "message": "Some fields need attention.",
    "fields": {"job_type": "Unknown value \"Fulltime\". See GET /v1/lookups for the ids and names."}
  }
}

Endpoints

Base address: https://workhook.co.za/api/v1. {ref} is the WorkHook job ref (e.g. kz99h22dbt) or ext: + your own external_ref (e.g. ext:ATS-10442).

Job fields

For lists (category, job_type, work_mode, level) send the id or the name from /lookups - short names work too when only one item fits, e.g. "On-site", "Hybrid" or "NQF 6". Countries take the ISO code (ZA). Fields marked * are needed to publish.

Update by your own id, then close it

curl -X PATCH https://workhook.co.za/api/v1/jobs/ext:ATS-10442 \
  -H "Authorization: Bearer whk_your_api_key" -H "Content-Type: application/json" \
  -d '{"closing_date": "2026-12-31", "salary": {"max": 26000}}'
# ...later, when the position is filled:
curl -X POST https://workhook.co.za/api/v1/jobs/ext:ATS-10442/close \
  -H "Authorization: Bearer whk_your_api_key" -H "Content-Type: application/json" \
  -d '{"status": "Filled"}'

Applications

curl "https://workhook.co.za/api/v1/applications?since=2026-10-27T08:00:00%2B02:00" -H "Authorization: Bearer whk_your_api_key"

{
  "id": 4821,
  "job": {"ref": "kz99h22dbt", "external_ref": "ATS-10442", "title": "Bookkeeper"},
  "status": "Applied",
  "applicant": {"name": "Thandi Mokoena", "email": "thandi@example.com", "phone": "082 555 0101", "country": "ZA", "city": "Pretoria", "experience_years": 6},
  "message": "I have six years of SME bookkeeping on Sage and Pastel ...",
  "quote": null,
  "available_from": "2026-11-15",
  "cv": {"name": "Thandi CV 2026", "format": "file", "download_url": "https://workhook.co.za/api/v1/applications/4821/cv"},
  "notes": null,
  "applied_at": "2026-10-27T09:14:02+02:00"
}

Move it along - and email the applicant if you like:

curl -X PATCH https://workhook.co.za/api/v1/applications/4821 \
  -H "Authorization: Bearer whk_your_api_key" -H "Content-Type: application/json" \
  -d '{"status": "Interview", "notify": true, "message": "Can you come in on Tuesday at 10:00?"}'

Statuses: Applied, Viewed, Shortlisted, Interview, Offered, Hired, Rejected (and Withdrawn, set by the applicant).

Webhooks

Set your webhook address on the API page. WorkHook then POSTs JSON to it when something happens - no polling needed:

• application.created - someone applied or sent a quote
• application.withdrawn - the applicant withdrew
• test - from the "Send a test" button or POST /webhooks/test

POST https://your-system.example/workhook-webhook
Content-Type: application/json
X-WorkHook-Event: application.created
X-WorkHook-Delivery: 913
X-WorkHook-Timestamp: 1793091242
X-WorkHook-Signature: sha256=5d1c...

{"id": 913, "event": "application.created", "created_at": "2026-10-27T09:14:02+02:00",
 "data": {"application": { ...same as GET /applications/{id}... }}}

Answer with any 2xx status within 6 seconds. Otherwise we try again after 5 minutes, 30 minutes, 2 hours and 6 hours. Check the signature so you know it came from WorkHook: HMAC-SHA256 of timestamp + "." + body with your signing secret.

$body = file_get_contents("php://input");
$ts   = $_SERVER["HTTP_X_WORKHOOK_TIMESTAMP"];
$sig  = $_SERVER["HTTP_X_WORKHOOK_SIGNATURE"];
$ok   = hash_equals("sha256=" . hash_hmac("sha256", $ts . "." . $body, $secret), $sig)
        && abs(time() - (int)$ts) < 300;
if (!$ok) { http_response_code(401); exit; }
$event = json_decode($body, true);

const crypto = require("crypto");
// rawBody = the exact request body as a string
const ts = req.headers["x-workhook-timestamp"];
const expected = "sha256=" + crypto.createHmac("sha256", secret)
  .update(ts + "." + rawBody).digest("hex");
const ok = crypto.timingSafeEqual(Buffer.from(expected),
  Buffer.from(req.headers["x-workhook-signature"] || ""));

Lookups

GET /lookups returns every list with ids and names. The current values: