Webhooks & Event Delivery
Wire up your first Oho outbound webhook in four steps: discover the event catalogue, subscribe, verify the signature on every delivery, and send a test event — with the receiver code for Node and Python. Each step links to its per-endpoint reference for the complete field and query-parameter list.
Once it's live, Webhook Operations covers running it: rotating the signing secret, reading the delivery history, and replaying failed or missed deliveries.
Three more companions carry the parts you reach for separately: the Webhook Payload Reference for the envelope and every event type's fields, the Webhook Endpoint Reference for the call that does each thing, and Recovering a Broken Webhook Endpoint for the runbook to follow after an outage.
For a plain-language overview of what webhooks are and when Oho sends them, see the Webhooks concept page.
Read API Basics first — it covers base URLs, the Authorization header, IDs, the
response envelope, and error shapes that every step here relies on. The examples assume $OHO_BASE
and $OHO_TOKEN are set. Calls to /webhooks need a token authorized for the webhook entity (READ
to list/get, CREATE to subscribe, UPDATE for rotate/ping/enable/disable/redrive, DELETE to remove) —
see Authentication & Tokens.
This guide is about outbound webhooks — Oho POSTing events to your endpoint. There is a
separate inbound surface under the police-check-webhooks tag where police-check providers
POST status updates back to Oho. They share a name and a signing scheme but point in opposite
directions; the inbound side is covered on
Webhook Operations.
- Endpoint base:
/openapi/v1/webhooks - URN:
urn:li:webhook:whk_<id> - Signature header:
X-Oho-Signature: t=<unix-millis>,v1=<hex-sha256> - Request timeout per attempt: 15 seconds
- Retry policy: exponential, max 6 attempts, capped at 60s between attempts
- Auto-disable threshold: 50 consecutive failures
1. Discover the event catalogue
Before subscribing, list the event types you can listen for. The catalogue is the source of truth — subscriptions to anything not in it are rejected at create time. The response below is abridged; the full list is in the table under it.
curl -sS "$OHO_BASE/webhooks/events" -H "Authorization: Bearer $OHO_TOKEN"
{
"data": [
{
"type": "credential.added",
"entityType": "credential",
"category": "lifecycle",
"description": "A Credential was created (any type — verifiable or custom)."
},
{
"type": "credential.updated",
"entityType": "credential",
"category": "lifecycle",
"description": "A Credential's stored fields were edited..."
},
{
"type": "credential.verified",
"entityType": "credential",
"category": "transition",
"description": "A Credential reached a verification outcome — from the issuing registry, or from a person deciding on one. Fires on every terminal outcome — MAY_ENGAGE, MAY_NOT_ENGAGE, REVIEW_REQUIRED — but not for IN_PROGRESS or transient ERROR..."
},
{
"type": "recruitmentCheck.completed",
"entityType": "recruitmentCheck",
"category": "lifecycle",
"description": "Recruitment check finished — every requested verifiable has a result. Payload carries credentials[] and policeChecks[] (submitted verifiables with their outcome), exemptions[] and declarations[] (the applicant's active records), and a bans summary (ban-check status + registries consented to)."
},
{
"type": "fetchRequest.completed",
"entityType": "fetchRequest",
"category": "lifecycle",
"description": "Fetch request finished — worker has submitted all requested credentials."
},
{
"type": "webhook.test",
"entityType": "webhook",
"category": "utility",
"description": "Synthetic test event delivered by POST /webhooks/{id}/ping."
}
],
"meta": { "requestId": "..." }
}
Subscriptions accept exact event types (e.g. credential.verified) and wildcards: <resource>.*
(every event for a resource), *.<action> (one action across resources), or * (firehose).
Wildcards are validated against this catalogue at subscription time — a pattern that matches nothing
is rejected. Full reference: List subscribable event types.
The events you can subscribe to:
| Event | Category | Fires when |
|---|---|---|
credential.added | lifecycle | A credential was created (any type — verifiable or custom). |
credential.updated | lifecycle | A credential's stored fields were edited. |
credential.verified | transition | A credential reached a terminal verification outcome — pass, fail or needs-a-decision. Branch on data.eligibility, not on the event itself. |
credential.linked | lifecycle | An owner (worker or applicant) was linked to a credential. |
credential.unlinked | lifecycle | An owner reference was removed from a credential. |
credential.transferred | lifecycle | A credential's owner moved from one holder to another (e.g. the applicant→worker hire flow). |
credential.attachmentAdded | lifecycle | A file was attached to a credential. |
credential.attachmentRemoved | lifecycle | A file was removed from a credential. |
credential.attachmentTransferred | lifecycle | Once per file, alongside credential.transferred, when the credential has files. |
credential.attachmentLinked | lifecycle | Once per file, alongside credential.linked, when the credential has files. |
credential.attachmentUnlinked | lifecycle | Once per file, alongside credential.unlinked, when the credential has files. |
qualification.added | lifecycle | A qualification was created, by any path. Fires once. |
qualification.updated | lifecycle | A field in the qualification changed — including register check, USI transcript and document review outcomes. |
qualification.linked | lifecycle | An owner (worker or applicant) was linked to a qualification — for example when an applicant is converted to a worker and their qualifications are carried across. |
qualification.unlinked | lifecycle | An owner reference was removed from a qualification. |
qualification.transferred | lifecycle | A qualification's owner moved from one holder to another. |
recruitmentCheck.completed | lifecycle | An applicant finished a recruitment check — every requested credential has a result. |
fetchRequest.completed | lifecycle | A worker finished a fetch request — every requested credential submitted. |
worker.added | lifecycle | A worker was added to the tenant. |
webhook.test | utility | A synthetic event you trigger with POST /webhooks/{id}/ping — useful for end-to-end testing. |
webhook.disabled | lifecycle | Oho auto-disabled a subscription after 50 consecutive delivery failures. |
webhook.disabled needs a separate subscriptionOnly ACTIVE subscriptions receive events, and the subscription that just tripped the threshold is
AUTO_DISABLED by the time the event is emitted — so it never hears about its own disabling. Point
a different endpoint at it, one you monitor separately:
{
"name": "webhook health",
"delivery": { "url": "https://ops.example.com/oho" },
"events": ["webhook.disabled"]
}
Payload fields are in the Payload Reference.
2. Subscribe (create a webhook)
name is the only required top-level field, but a useful subscription also needs a delivery.url
and at least one events entry. The server generates a synthetic whk_ ID and a fresh signing
secret, returns 201 with a Location header, and includes the plaintext signing secret exactly
once under data.attributes.delivery.signingSecret. Save it now — there is no API to read it back.
See Create webhook subscription for every field.
curl -sS -X POST "$OHO_BASE/webhooks" \
-H "Authorization: Bearer $OHO_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "Compliance dashboard sync",
"description": "Owned by #compliance-eng — JIRA OHO-1234",
"delivery": { "url": "https://compliance.example.com/oho/webhook" },
"events": ["credential.verified", "recruitmentCheck.completed"],
"retry": { "maxAttempts": 6, "backoff": "EXPONENTIAL" }
}'
{
"data": {
"id": "whk_2bX9pK4mN1qR8sT3",
"type": "webhook",
"attributes": {
"name": "Compliance dashboard sync",
"description": "Owned by #compliance-eng — JIRA OHO-1234",
"delivery": {
"url": "https://compliance.example.com/oho/webhook",
"status": "ACTIVE",
"signingSecret": "g6vN5kP3qR8sT4uV2wX1yZ0aB7cD9eF6hJ4kL5mN8pQ",
"signingSecretLastFour": "N8pQ",
"signingSecretRotatedAt": "2026-06-29T02:14:07Z"
},
"events": ["credential.verified", "recruitmentCheck.completed"],
"retry": { "maxAttempts": 6, "backoff": "EXPONENTIAL" },
"audit": {
"createdAt": "2026-06-29T02:14:07Z",
"createdBy": "urn:li:corpuser:..."
}
}
},
"meta": { "requestId": "..." }
}
export WHK="whk_2bX9pK4mN1qR8sT3"
export OHO_WEBHOOK_SECRET="<signingSecret from the response above>"
On every subsequent read the secret is scrubbed — only signingSecretLastFour comes back. If you
lose it, your only recovery is rotation, which invalidates the old
value. Put it in your secret manager before moving on.
The aspect invariants are enforced for every write path (OpenAPI, GraphQL, ingestion), so they hold
here too. Each returns 400:
namemissing →name is requireddelivery.urlnothttps://→ rejected by the validatordelivery.urlpointing at a private or internal network address (loopback,10.x,172.16-31.x,192.168.x, link-local, or a bare name with no domain) → rejected. Those reach machines inside Oho's own systems, never yours. The address is checked again just before each delivery, so a hostname that starts resolving internally fails that delivery permanently withDestination refusedon the delivery record.eventscontaining a type or wildcard not in the catalogue → rejected- Basic auth (
delivery.basicAuthUsername+delivery.basicAuthPasswordSecret) and bearer auth (delivery.bearerTokenSecret) supplied together — they are mutually exclusive
Optional: narrow what fires
Add a filters block so only the events you care about reach your endpoint:
{
"filters": {
"entityTypes": ["credential"],
"organisations": ["urn:li:organization:..."],
"ownerExternalIds": ["WD-100482"],
"jurisdictions": ["VIC", "NSW"]
}
}
| Field | Effect |
|---|---|
entityTypes | Only events on these entity URN types (e.g. ["credential"]). |
organisations | Only events about records in these organisations. Use the organisation URN, its id, or its name. |
ownerExternalIds | Only events for workers/applicants whose external id matches. For a credential, its holder's external id is used. |
jurisdictions | Only events from credentials in these jurisdictions (e.g. ["VIC", "NSW"]). |
Filters combine with AND, and each list matches any of its values. Oho works out an event's
organisation, owner and jurisdiction from the record the event is about. When it can't (a record
with no organisation, or a non-credential event under a jurisdictions filter), the event is
not sent to a subscription that filters on it, so a filtered subscription never receives an
event it can't be shown to be scoped for.
Optional: authenticate to your endpoint
If your receiver needs Basic or bearer auth on top of the signature, reference an Oho secret by name — the credential itself never touches the webhook record. Oho stores the secret encrypted server-side. Create it either inline from the secret picker as you add the webhook under Settings → Developer → Webhooks, or ahead of time under Admin → Data Sources → Secrets (both need the Manage Secrets privilege). Then point at it by its ref name:
{
"delivery": {
"basicAuthUsername": "oho-webhook",
"basicAuthPasswordSecret": "webhook-basic-auth-pw"
}
}
Bearer token (a single token held in Oho's secret store):
{
"delivery": {
"bearerTokenSecret": "webhook-bearer-token"
}
}
In both cases Oho resolves and decrypts the secret at delivery time; the token/password is never
stored on the subscription or returned by the API. Read responses surface only the secret ref name
plus a read-only basicAuthConfigured / bearerTokenConfigured flag. Basic and Bearer are mutually
exclusive — both set the Authorization header, so supplying both in one request is rejected with
400. Selecting one mode clears the other's fields; an edit that touches neither leaves the
configured auth untouched.
Manage the subscription afterwards with Get, List,
Partially update (merge-patch), Replace, and
Soft delete. Note: delivery.signingSecret is rejected on PATCH/PUT —
use /rotate.
3. Verify the signature on every delivery
Every delivery carries an HMAC-SHA256 signature in the X-Oho-Signature header. Verifying it is
mandatory — without it, anyone who learns your URL can forge events.
Each request from Oho includes:
| Header | Value |
|---|---|
Content-Type | application/json; charset=utf-8 |
X-Oho-Event | The event type (e.g. credential.verified). |
X-Oho-Delivery | The same UUID as deliveryId in the body. Use as an idempotency key. |
X-Oho-Tenant | The Oho deployment tenant slug (e.g. xref-poc) — the same value as tenant.id in the body. Unsigned, so use it only for edge routing; trust the signed body's tenant.id for anything security-relevant. |
X-Oho-Signature | t=<unix-millis>,v1=<hex-sha256> — carries one or more v1= values (see below). |
Authorization | Basic <base64(user:pass)> if you configured Basic auth, or Bearer <token> if you configured a bearer token — only one can be set (see endpoint authentication). |
| Custom headers | Anything you added via customHeaders at create time (with six reserved names — content-type, authorization, x-oho-event, x-oho-delivery, x-oho-tenant, x-oho-signature — silently dropped if you try). |
The signed payload is the timestamp, a literal ., then the raw request body bytes:
signed_payload = "<t>" + "." + <raw-request-body>
v1 = hex( HMAC-SHA256(signing_secret, signed_payload) )
Two details trip people up most often:
<raw-request-body>is the body as bytes — exactly what arrived over the wire, before any JSON parsing or pretty-printing. If your framework re-serialises the JSON before handing it to your handler, the recomputed signature will not match. Read the raw body before parsing.- The timestamp goes inside the signed payload, not as a separate field. Don't try to verify just the body — you'll get a different digest.
Header format
X-Oho-Signature: t=1717900215496,v1=4d3c2a1b0e9f8d7c6b5a4f3e2d1c0b9a8f7e6d5c4b3a29180716050403020100
| Key | Meaning |
|---|---|
t | Unix epoch in milliseconds at the moment Oho computed the signature. |
v1 | A signature — lowercase hex of an HMAC-SHA256 digest. The header may carry more than one v1 entry. |
The v1 prefix is a versioning hook. If Oho ever rolls a stronger algorithm we'll add v2=…
alongside v1 so both old and new receivers keep working during transition.
More than one v1: during a secret rotation overlap window, Oho
signs each delivery with both the new and the previous secret and sends both signatures — e.g.
t=...,v1=<new>,v1=<old>. Collect every v1 value and treat verification as a pass if any
of them matches your configured secret. Parsing the header into a map keyed by v1 is a bug — it
discards all but one signature and will reject half of your deliveries mid-rotation.
Receiver code
The receiver, for the two most common stacks. The logic is identical: read the raw bytes,
parse the header, recompute the digest over t + . + body, compare in constant time, and
reject anything older than the replay window.
- Node.js (Express)
- Python (Flask)
import crypto from "node:crypto";
const OHO_WEBHOOK_SECRET = process.env.OHO_WEBHOOK_SECRET;
const MAX_AGE_MS = 5 * 60 * 1000; // 5-minute replay window
function verifyOhoSignature(signatureHeader, rawBody) {
if (!signatureHeader) return false;
// Parse `t=...,v1=...` — collect ALL v1 entries (there may be two during a rotation overlap).
let timestamp;
const signatures = [];
for (const kv of signatureHeader.split(",")) {
const idx = kv.indexOf("=");
const k = kv.slice(0, idx).trim();
const v = kv.slice(idx + 1).trim();
if (k === "t") timestamp = v;
else if (k === "v1") signatures.push(v);
}
if (!timestamp || signatures.length === 0) return false;
// Reject deliveries that are too old (replay protection)
if (Math.abs(Date.now() - Number(timestamp)) > MAX_AGE_MS) return false;
// Recompute the digest
const expected = crypto
.createHmac("sha256", OHO_WEBHOOK_SECRET)
.update(`${timestamp}.${rawBody}`)
.digest("hex");
const a = Buffer.from(expected, "hex");
// Constant-time comparison against every offered signature — a match on any one passes.
return signatures.some((provided) => {
const b = Buffer.from(provided, "hex");
return a.length === b.length && crypto.timingSafeEqual(a, b);
});
}
Express handler tying it together — note the use of express.raw() so we get the bytes exactly as
Oho signed them:
import express from "express";
const app = express();
app.post(
"/oho/webhook",
express.raw({ type: "application/json" }),
(req, res) => {
const sig = req.headers["x-oho-signature"];
const rawBody = req.body.toString("utf8");
if (!verifyOhoSignature(sig, rawBody)) {
return res.status(401).send("invalid signature");
}
const event = JSON.parse(rawBody);
// Idempotency — drop if we've seen this deliveryId before
if (alreadyProcessed(event.deliveryId)) {
return res.status(200).send("ok (duplicate)");
}
// credential.* and qualification.* carry the full current record: upsert on
// data.credential.credentialId / data.qualification.qualificationId.
handleEvent(event);
res.status(200).send("ok");
},
);
import hmac
import hashlib
import os
import time
from flask import Flask, request, abort
OHO_WEBHOOK_SECRET = os.environ["OHO_WEBHOOK_SECRET"].encode()
MAX_AGE_MS = 5 * 60 * 1000
def verify_oho_signature(signature_header: str, raw_body: bytes) -> bool:
if not signature_header:
return False
# Collect ALL v1 entries — a rotation overlap sends two (new + old secret).
timestamp = None
signatures = []
for kv in signature_header.split(","):
key, _, value = kv.strip().partition("=")
if key == "t":
timestamp = value
elif key == "v1":
signatures.append(value)
if not timestamp or not signatures:
return False
if abs(int(time.time() * 1000) - int(timestamp)) > MAX_AGE_MS:
return False
signed_payload = f"{timestamp}.".encode() + raw_body
expected = hmac.new(OHO_WEBHOOK_SECRET, signed_payload, hashlib.sha256).hexdigest()
# A match on any offered signature is a pass (constant-time compare).
return any(hmac.compare_digest(expected, provided) for provided in signatures)
app = Flask(__name__)
@app.post("/oho/webhook")
def handle():
raw = request.get_data() # bytes, exactly as received
if not verify_oho_signature(request.headers.get("X-Oho-Signature", ""), raw):
abort(401)
# ... process event ...
return ("ok", 200)
Common signature-verification mistakes
| Mistake | Result |
|---|---|
| Using parsed/re-serialised JSON instead of the raw body | Digest mismatch — every event rejected. |
Comparing strings with == instead of hmac.compare_digest / crypto.timingSafeEqual | Vulnerable to timing attacks. |
Treating t as seconds instead of milliseconds | Replay window check rejects fresh events. |
Forgetting the . separator between t and the body | Digest mismatch. |
Allowing requests with no X-Oho-Signature header through | Trivial spoofing. |
Reading only one v1 (e.g. a dict keyed by v1) instead of checking every entry | Half your deliveries rejected mid-rotation. |
The body uses one envelope for every event; the per-event fields live under data — see the
Webhook Payload Reference for the full structure and field-by-field
breakdown:
{
"deliveryId": "0167d799-f51c-41a9-a777-58a65bb7d305",
"eventType": "credential.verified",
"emittedAt": "2026-06-29T02:23:35.496341557Z",
"entityUrn": "urn:li:credential:...",
"tenant": { "id": "xref-poc", "url": "https://xref-poc.weareoho.com" },
"data": { "...": "event-specific" }
}
4. Send a test event (ping)
Before you depend on real traffic, fire a synthetic webhook.test straight at your URL. Ping is
synchronous and deliberately bypasses the event-pattern filter and the active-status check, so it
works on a brand-new or even disabled subscription. See Send a test event.
curl -sS -X POST "$OHO_BASE/webhooks/$WHK/ping" -H "Authorization: Bearer $OHO_TOKEN"
{
"data": {
"delivered": true,
"statusCode": 200,
"message": null,
"deliveredAt": "2026-06-29T03:20:00Z"
},
"meta": { "requestId": "..." }
}
A delivered: false with a statusCode/message tells you exactly why the round-trip failed —
ideal as a smoke test on every deploy of your receiver.
Next: run it in production
That's the first-webhook path done. When you need to rotate the secret, check what was delivered, or replay deliveries your endpoint missed, see → Webhook Operations.
Payload reference
Every delivery uses a common envelope, and each event type carries its own data body. Both are
documented in full on their own page:
→ Webhook Payload Reference — the envelope fields, and a
field-by-field breakdown of credential.verified, credential.added / credential.updated,
recruitmentCheck.completed, the ownership events,
the qualification events, webhook.test, and
webhook.disabled.
Process qualification.* events as upserts keyed on data.qualification.qualificationId, as you
key credential.* events on data.credential.credentialId — see
Upserting from qualification events.
Recovering from a broken endpoint
Had an outage — a deploy that broke verification for an hour, an expired cert, a database that went away? There's a six-step runbook for finding what you missed, replaying what's recoverable, and reconciling the rest by reading current state:
→ Recovering a Broken Webhook Endpoint
All webhook endpoints
Every endpoint that manages a subscription — create, read, patch, replace, delete, enable, disable, rotate, ping, deliveries, redrive — plus the two replay endpoints that live on the recruitment-check resource, are listed on their own page:
→ Webhook Endpoint Reference — what each call does, and the token authorization every one of them needs.
Recommended setup
- Create the subscription with
events: ["credential.verified", "recruitmentCheck.completed", "fetchRequest.completed"]— covers the high-value lifecycle events. - Store the signing secret in your platform's secret manager. Treat it like a database password.
- Read raw bytes before parsing in your handler.
- Verify the signature with
timingSafeEqual/hmac.compare_digest. - Reject deliveries older than 5 minutes using the
tvalue. - Dedupe on
deliveryIdbefore doing any side-effectful work — retries are normal. - Return 200 quickly, then process asynchronously if the work is heavy. The 15-second timeout is generous but not unlimited.
- Fire
POST /webhooks/{id}/pingas a smoke test on every deploy — it exercises the full path including signature verification.
Where to go next
- Webhook Operations — rotate the secret, read delivery history, redrive and replay
- Webhook Payload Reference — the delivery envelope and every event type's
databody - Webhook Endpoint Reference — every subscription-management call in one table
- Recovering a Broken Webhook Endpoint — the six-step runbook for after an outage
- Webhooks — a plain-language overview of what webhooks are and when Oho sends them (for non-technical readers)
- API Reference — every endpoint, field, and query parameter
- Workers & Credentials tutorial — the verify flow that emits
credential.verified