API and webhooks

Getting started

API keys and webhooks are part of the paid recruiter plans. The account owner (head of HR) sets them up in Settings → Integrations in the HireVation dashboard.

• API: your software asks HireVation for data (“give me the applicants for this job”).
• Webhooks: HireVation tells your software the moment something happens (“a candidate just applied”). No polling needed.

API keys

Create a key in Settings → Integrations → API keys. The full key starts with hv_live_ and is shown once; store it somewhere safe, like a password. Send it with every request, either way:

Authorization: Bearer hv_live_xxxxxxxxxxxxxxxx
X-API-Key: hv_live_xxxxxxxxxxxxxxxx

Test your key:

curl https://hirevation.com/api/v1/me/ -H "Authorization: Bearer hv_live_xxxxxxxx"

API endpoints

Base address: https://hirevation.com/api/v1/. All answers are JSON. Lists take ?limit= (1–100, default 25) and ?offset=, are newest first, and include total.

Example answer from /jobs/{job_id}/applications/:

{"total": 1, "limit": 25, "offset": 0, "results": [
  {"id": "6f0c…", "job_id": "a1b2…", "job_title": "IT Support Engineer", "name": "Sara Ahmed",
   "email": "sara@example.com", "status": "new", "applied_at": "2026-11-09T10:00:00Z",
   "results_status": "shared", "linkedin_url": "https://www.linkedin.com/in/sara-ahmed/",
   "hirevation_results": [{"name": "IT Support Specialist", "score": 86, "level": "Advanced", "report_id": "HV-ITS-7Q2K"}],
   "dashboard_url": "https://hirevation.com/app/"}]}

A team owner's key sees the whole team's work, the same as the dashboard.

Webhooks

Add a web address in Settings → Integrations → Webhooks and tick the events you want. HireVation then sends a POST with a JSON body to that address each time one happens:

{"id": "evt_3f9a…", "event": "application.created", "created_at": "2026-11-09T10:00:00Z",
 "data": { …the same fields as the API… }}

Headers on every call:

Answer with any 2xx code within 8 seconds. If not, HireVation tries again after 10 seconds and after 60 seconds. After 20 failures in a row the address is switched off; switch it back on in Settings. The last calls and their results are listed there, and Send test sends a sample call.

Events

Checking the signature

Each address has its own secret (starts with whsec_, shown in Settings). Work out an HMAC-SHA256 of <t>.<raw body> with the secret and compare it with v1. Reject calls older than 5 minutes.

Python

import hmac, hashlib, time

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

Node.js

const crypto = require("crypto");
function isFromHireVation(rawBody, header, secret) {
  const parts = Object.fromEntries(header.split(",").map(p => p.split("=")));
  if (Math.abs(Date.now() / 1000 - Number(parts.t)) > 300) return false;
  const expected = crypto.createHmac("sha256", secret).update(parts.t + "." + rawBody).digest("hex");
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1));
}

Zapier and Make (no code)

Zapier: send every new applicant to Google Sheets

1. In Zapier, create a Zap. Trigger: Webhooks by Zapier → Catch Hook. Copy the address Zapier gives you.
2. In HireVation, Settings → Integrations → Add webhook: paste the address, tick application.created, save, then press Send test.
3. Back in Zapier, press Test trigger: the sample applicant appears.
4. Action: Google Sheets → Create Spreadsheet Row, and match the columns to data name, data email, data job_title…
5. Turn the Zap on. Every new applicant now lands in your sheet.

Make

1. Create a scenario starting with Webhooks → Custom webhook and copy its address.
2. Add it in HireVation as above and press Send test so Make learns the fields.
3. Add any module after it: Gmail, Slack, Notion, HubSpot, your ATS…

Reading data with Zapier or Make

Use Webhooks by Zapier → GET (or Make's HTTP → Make a request) with the API address and the header Authorization: Bearer hv_live_….

Limits and safety

• Up to 600 API requests an hour per account; above that you get 429. Wait and try again.
• Up to 10 API keys and 10 webhook addresses per account.
• Webhook addresses must be https:// on the public internet. Redirects are not followed.
• Keys and webhook secrets are secrets: never put them in a web page or share them in chat. If one leaks, revoke the key or press New secret.
• Candidate data you receive is personal data. Use it only for hiring and keep it safe, as in our privacy policy.