Skip to main content

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.

Before you start

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.

Two different "webhooks" in Oho

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.

Quick reference
  • 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:

EventCategoryFires when
credential.addedlifecycleA credential was created (any type — verifiable or custom).
credential.updatedlifecycleA credential's stored fields were edited.
credential.verifiedtransitionA credential reached a terminal verification outcome — pass, fail or needs-a-decision. Branch on data.eligibility, not on the event itself.
credential.linkedlifecycleAn owner (worker or applicant) was linked to a credential.
credential.unlinkedlifecycleAn owner reference was removed from a credential.
credential.transferredlifecycleA credential's owner moved from one holder to another (e.g. the applicant→worker hire flow).
credential.attachmentAddedlifecycleA file was attached to a credential.
credential.attachmentRemovedlifecycleA file was removed from a credential.
credential.attachmentTransferredlifecycleOnce per file, alongside credential.transferred, when the credential has files.
credential.attachmentLinkedlifecycleOnce per file, alongside credential.linked, when the credential has files.
credential.attachmentUnlinkedlifecycleOnce per file, alongside credential.unlinked, when the credential has files.
qualification.addedlifecycleA qualification was created, by any path. Fires once.
qualification.updatedlifecycleA field in the qualification changed — including register check, USI transcript and document review outcomes.
qualification.linkedlifecycleAn 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.unlinkedlifecycleAn owner reference was removed from a qualification.
qualification.transferredlifecycleA qualification's owner moved from one holder to another.
recruitmentCheck.completedlifecycleAn applicant finished a recruitment check — every requested credential has a result.
fetchRequest.completedlifecycleA worker finished a fetch request — every requested credential submitted.
worker.addedlifecycleA worker was added to the tenant.
webhook.testutilityA synthetic event you trigger with POST /webhooks/{id}/ping — useful for end-to-end testing.
webhook.disabledlifecycleOho auto-disabled a subscription after 50 consecutive delivery failures.
webhook.disabled needs a separate subscription

Only 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>"
Store the secret immediately

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.

Validation errors

The aspect invariants are enforced for every write path (OpenAPI, GraphQL, ingestion), so they hold here too. Each returns 400:

  • name missing → name is required
  • delivery.url not https:// → rejected by the validator
  • delivery.url pointing 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 with Destination refused on the delivery record.
  • events containing 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"]
}
}
FieldEffect
entityTypesOnly events on these entity URN types (e.g. ["credential"]).
organisationsOnly events about records in these organisations. Use the organisation URN, its id, or its name.
ownerExternalIdsOnly events for workers/applicants whose external id matches. For a credential, its holder's external id is used.
jurisdictionsOnly 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:

HeaderValue
Content-Typeapplication/json; charset=utf-8
X-Oho-EventThe event type (e.g. credential.verified).
X-Oho-DeliveryThe same UUID as deliveryId in the body. Use as an idempotency key.
X-Oho-TenantThe 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-Signaturet=<unix-millis>,v1=<hex-sha256> — carries one or more v1= values (see below).
AuthorizationBasic <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 headersAnything 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:

  1. <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.
  2. 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
KeyMeaning
tUnix epoch in milliseconds at the moment Oho computed the signature.
v1A 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.

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");
},
);

Common signature-verification mistakes​

MistakeResult
Using parsed/re-serialised JSON instead of the raw bodyDigest mismatch — every event rejected.
Comparing strings with == instead of hmac.compare_digest / crypto.timingSafeEqualVulnerable to timing attacks.
Treating t as seconds instead of millisecondsReplay window check rejects fresh events.
Forgetting the . separator between t and the bodyDigest mismatch.
Allowing requests with no X-Oho-Signature header throughTrivial spoofing.
Reading only one v1 (e.g. a dict keyed by v1) instead of checking every entryHalf 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.

  1. Create the subscription with events: ["credential.verified", "recruitmentCheck.completed", "fetchRequest.completed"] — covers the high-value lifecycle events.
  2. Store the signing secret in your platform's secret manager. Treat it like a database password.
  3. Read raw bytes before parsing in your handler.
  4. Verify the signature with timingSafeEqual / hmac.compare_digest.
  5. Reject deliveries older than 5 minutes using the t value.
  6. Dedupe on deliveryId before doing any side-effectful work — retries are normal.
  7. Return 200 quickly, then process asynchronously if the work is heavy. The 15-second timeout is generous but not unlimited.
  8. Fire POST /webhooks/{id}/ping as a smoke test on every deploy — it exercises the full path including signature verification.

Where to go next​