The same API the app uses, with your own key

Webhooks, when Vayora should call you

Every activity event Vayora records, from a stage change to a note, can go to an endpoint you choose. Each one is signed, so your side can check it came from Vayora. That is how Zapier, Make and n8n listen without polling.

1. 1. Register it as an admin. Send POST /admin/webhooks with the endpoint's url and the events you want. It takes an account admin's own signed-in token as Authorization: Bearer. An API key gets a 403, because a key acts as a recruiter. The endpoint has to be a public https address, and a workspace can have up to 25.
2. 2. Pick the events. stage_change when a candidate moves stage on a role, Placed included. An accepted offer moves the card to Placed too. note_added when someone saves a note on a record. note when a note is logged through POST /candidate/{candidate_id}/activity. Or "*" for every activity event.
3. 3. Check the signature. Each delivery is a POST whose JSON body holds event and data. Its X-VYR-Signature header is the HMAC-SHA256 of the raw body in hex, keyed with the secret the create call returned. Work out the same over the bytes you received and compare the two.
4. 4. Keep an eye on it. GET /admin/webhooks lists them with each one's secret, last delivery and failure count. PUT /admin/webhooks/{webhook_id} changes the url, the events or the active flag, and DELETE on the same path removes it. Each event goes to each matching webhook once, and Vayora waits up to 5 seconds for an answer.

Rather set it up in the app? On Pro, an automation rule (Settings, then Automation) can call a webhook when a candidate applies, replies, moves stage or sits on a role with no activity, and when a pitch moves stage. Give the rule a signing secret and each call carries an X-Vayora-Signature header. Its value is sha256= followed by the HMAC-SHA256 of the body in hex.

Use them together: a webhook tells you something has happened, and a key lets you act on it.

Register a webhook

curl https://api.vayora.co/admin/webhooks \
  -H "Authorization: Bearer your_admin_access_token" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://hooks.example.com/vayora",
       "events": ["stage_change", "note_added"]}'

Response

{"webhook_id": "wh_3f2a9c1b7d4e",
 "url": "https://hooks.example.com/vayora",
 "events": ["stage_change", "note_added"],
 "secret": "Vn4qXc1bT8kLp2RzE7sWd0YhGu5mJa9fKiOe3NtQwBy",
 "active": true, "created_at": "2026-10-24T09:12:31.482913+00:00",
 "last_triggered_at": null, "failure_count": 0}

What arrives

POST https://hooks.example.com/vayora
Content-Type: application/json
X-VYR-Signature: 4f1cca5b582109cdffe81e9bd68a3ddcf4e75eb20bf2fd782265a6476a839297

{"event": "stage_change", "data": {
  "event_id": "evt-5b0e2c7a91d3", "event_type": "stage_change",
  "account_id": "acc_7d1f0a9c3e52",
  "description": "Moved from offer to hired",
  "occurred_at": "2026-10-24T09:15:02.118204+00:00",
  "actor_id": "usr-4c8e1b7f2a90", "actor_name": null,
  "entity": {"type": "candidate", "id": "cand-9026bd0dd8a0"},
  "candidate_id": "cand-9026bd0dd8a0", "client_id": null,
  "contact_id": null, "requisition_id": "req-2e6a9d4b1c08",
  "submission_id": null, "placement_id": null,
  "metadata": {"from_stage": "offer", "to_stage": "hired", "note": ""}}}

Spread across lines here to read. It arrives on one line, and the signature covers those exact bytes. Check the raw body before you parse it. Signed with the example secret above, this body gives this signature.

Check the signature

import hashlib, hmac

def from_vayora(raw_body: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature)