Webhooks
Receive report outcomes and alerts instead of polling.
Reports run asynchronously. Webhooks are how you find out they finished.
Payloads are deliberately narrow: they carry the outcome, the risk and the evidence, and never the subject's name, email, phone number or internal identifiers.
The short version
Subscribe to report.ready and report.failed, and handle them like this:
app.post("/hooks/verifisha", (req, res) => {
res.sendStatus(200); // acknowledge first, work after
const { lifecycle, report, checks } = req.body;
if (!lifecycle.terminal) return; // progress only
for (const check of checks ?? []) {
if (check.status !== "COMPLETED") continue;
applyPolicy(check.name, check.riskLevel, check.flags);
}
});Three rules cover most of what follows: acknowledge with a 2xx before you
do any work, act only when lifecycle.terminal is true, and read
riskLevel and flags, not status, to decide anything.
The rest of this page is the detail — every event, every payload, and how to verify a delivery.
Configure a destination
POST /api/v1/webhooks/config
replaces the configuration wholesale — send the complete enabledEvents list,
not a change.
curl -X POST "https://api.verifisha.com/api/v1/webhooks/config" \
-H "Authorization: Bearer vrf_live_..." \
-H "Content-Type: application/json" \
-d '{
"url": "https://example.com/hooks/verifisha",
"enabled": true,
"enabledEvents": [
"report.ready",
"report.failed",
"check.completed",
"check.failed",
"monitoring.alert.created"
],
"secret": "replace-with-a-long-random-secret"
}'The secret is yours to choose, and it is write-only: it is never returned by
the API, so keep it in your own secret store.
Events
| Event | Fires when |
|---|---|
check.started | A check began. Hosted checks — liveness, AML screening — emit this while they wait on the subject. |
check.completed | A check finished running. |
check.failed | A check could not complete. |
report.ready | Every check in the report reached a terminal state. |
report.failed | The report could not be completed. |
monitoring.alert.created | A recurring check raised an alert. |
test.ping | You called the test endpoint. |
Subscribe to the check events for progress as it happens; subscribe to the
report events when your workflow needs every result together. Most
integrations want report.ready and report.failed, and nothing else.
Is this event final?
Start with lifecycle:
| Field | Meaning |
|---|---|
lifecycle.event | The event name, matching X-Verifisha-Event. |
lifecycle.resource | check for a single check, report for the whole report. |
lifecycle.terminal | true when no further processing is expected for that resource. |
Act on a check only when terminal is true. A check.started delivery is a
progress signal — record the report and check IDs, then wait.
COMPLETED means the check ran, not that the subject passed. A check that
finds a sanctions match is COMPLETED with a high riskLevel, and a report
whose checks all ran is report.ready even when one needs review. FAILED is
the opposite — an execution failure, never a finding about the subject.
Statuses and outcomes sets out all three kinds of "success", and which one you are looking at.
Headers
| Header | Value |
|---|---|
X-Verifisha-Event | The event name, e.g. report.ready. |
X-Verifisha-Delivery | Delivery identifier. Matches the delivery log entry. |
X-Verifisha-Environment | live or sandbox. |
X-Verifisha-Signature | Signature computed with your webhook secret. |
Verify the signature before trusting a payload, and verify it against the raw body bytes as received — re-serialising the JSON first will not match.
Check X-Verifisha-Environment before acting. A sandbox delivery carries the
same shape as a live one, and should not move anything in your production
systems.
report.ready
Sent when a report reaches a terminal state other than failure. Read
report.status to know which — a report that needs a reviewer
(PENDING_REVIEW) arrives on this event just as a clear one does. checks
carries one entry per check.
{
"schemaVersion": "2026-09-23",
"environment": "LIVE",
"workspaceId": "0a000137-a0cd-164f-81a0-cde9e7760000",
"lifecycle": {
"event": "report.ready",
"resource": "report",
"terminal": true
},
"report": {
"id": "0a00018c-a11a-1cc8-81a1-1a5064aa0028",
"environment": "LIVE",
"workspaceId": "0a000137-a0cd-164f-81a0-cde9e7760000",
"status": "COMPLETED",
"riskLevel": "LOW",
"compositeScore": 10,
"createdAt": "2026-10-08T07:00:41Z",
"completedAt": "2026-10-08T07:01:12Z",
"selfVerification": false,
"paymentMode": "SELF",
"consentStatus": "APPROVED",
"checkCount": 1,
"conclusion": {
"title": "Clear",
"description": "The report completed with low-risk findings."
}
},
"subject": {
"type": "INDIVIDUAL"
},
"checks": [
{
"id": "0a00018c-a11a-1cc8-81a1-1a50954b0033",
"definitionId": "8038f7a9-ea96-4b38-8be8-ea201399f406",
"name": "IDENTITY",
"displayName": "Kenyan Identity Check",
"category": "Identity",
"status": "COMPLETED",
"riskLevel": "LOW",
"riskScore": 10,
"summary": "Identity verified against official identity records",
"flags": [],
"evidenceDetails": [
{ "key": "checkType", "label": "Check type", "value": "Identity" },
{ "key": "outcome", "label": "Outcome", "value": "Clear" },
{ "key": "result.Document type", "label": "Document type", "value": "National ID" },
{ "key": "result.Date of birth", "label": "Date of birth", "value": "1992-01-29" },
{ "key": "result.Citizenship", "label": "Citizenship", "value": "Kenyan" }
],
"executedAt": "2026-10-08T07:01:12Z",
"durationMs": 2413
}
]
}The envelope
| Field | Description |
|---|---|
schemaVersion | The payload version. Log it — it is how you will know a shape changed. |
environment | LIVE or SANDBOX. |
workspaceId | The workspace the report belongs to. |
lifecycle.event | The event name, matching X-Verifisha-Event. |
lifecycle.resource | What the event is about, e.g. report. |
lifecycle.terminal | true when nothing further will arrive for this resource. |
subject.type | INDIVIDUAL or BUSINESS. The subject's identity is not included. |
The report
| Field | Description |
|---|---|
report.id | Use it to fetch the full record. |
report.status | Which terminal state it reached. Branch on this, not on the event name alone. |
report.riskLevel | Aggregate band across the checks — LOW, MEDIUM, HIGH, CRITICAL, or UNKNOWN when no score could be derived. |
report.compositeScore | Aggregate score, 0–100. null when no score could be derived. |
report.checkCount | How many checks the report ran. |
report.conclusion | A title and description written for people — show it, do not parse it. |
report.consentStatus | How consent stood when the report ran. |
report.paymentMode | Who paid. |
report.selfVerification | Whether the report was a workspace verifying itself. |
report.createdAt / completedAt | When the report was created, and when it reached this state. |
Each check
| Field | Description |
|---|---|
name | The check, as named in checksRequested. |
displayName / category | Safe to show in your own UI. |
status | Whether the check ran: PENDING, RUNNING, COMPLETED, FAILED, SKIPPED or CANCELLED. Not what it found. |
riskLevel / riskScore | LOW, MEDIUM, HIGH, CRITICAL or UNKNOWN, and a 0–100 score. This is what the check found. |
summary | One line written for people, not for parsing. |
flags | Adverse findings. Empty when there are none. |
evidenceDetails[] | key, label and value triples backing the outcome. |
executedAt / durationMs | When the check ran, and how long it took. |
evidenceDetails differs by check — an identity check returns document type
and citizenship, a credit check returns something else entirely. Render
label and value as given rather than expecting a fixed set; branch on
riskLevel and flags instead. Where you do need a specific field, match on
key.
evidenceDetails can still contain personal information about the subject —
a date of birth, for example. Accept deliveries over HTTPS only, and store
payloads with the same care as the report itself.
report.failed
Same envelope, sent when the report could not be completed. compositeScore is
null, riskLevel is UNKNOWN, and any checks that were attempted are
included with what went wrong in flags.
{
"schemaVersion": "2026-09-23",
"environment": "LIVE",
"workspaceId": "0a000137-a0cd-164f-81a0-cde9e7760000",
"lifecycle": {
"event": "report.failed",
"resource": "report",
"terminal": true
},
"report": {
"id": "0a00018c-a11a-1cc8-81a1-1a5064aa0028",
"status": "FAILED",
"riskLevel": "UNKNOWN",
"compositeScore": null,
"checkCount": 1,
"conclusion": {
"title": "Could not complete",
"description": "The report could not be completed successfully."
},
"createdAt": "2026-10-08T07:00:41Z",
"completedAt": "2026-10-08T07:01:12Z"
},
"subject": { "type": "INDIVIDUAL" },
"checks": [
{
"id": "0a00018c-a11a-1cc8-81a1-1a50954b0033",
"name": "IDENTITY",
"displayName": "Kenyan Identity Check",
"status": "FAILED",
"riskLevel": "UNKNOWN",
"summary": "The identity check could not be completed.",
"flags": ["Identity record lookup failed"],
"evidenceDetails": [
{ "key": "checkType", "label": "Check type", "value": "Identity" },
{ "key": "status", "label": "Status", "value": "Failed" }
],
"executedAt": "2026-10-08T07:01:12Z",
"durationMs": 2413
}
]
}A failed report is terminal. Nothing further arrives for it.
check.started
Emitted when a check begins. Hosted checks — liveness, AML screening — send this while they wait on the subject, so you can show progress.
{
"lifecycle": { "event": "check.started", "resource": "check", "terminal": false },
"report": { "id": "rpt_456", "status": "PROCESSING" },
"check": {
"id": "chk_aml_456",
"name": "AML_CHECK",
"status": "RUNNING",
"summary": "Hosted verification is in progress"
}
}terminal is false. Record the IDs and wait.
check.completed
One check finished running. The result sits under check, and report.status
tells you the report is still PROCESSING — other checks may still be going.
{
"schemaVersion": "2026-09-23",
"environment": "LIVE",
"workspaceId": "ws_123",
"lifecycle": { "event": "check.completed", "resource": "check", "terminal": true },
"report": { "id": "rpt_123", "status": "PROCESSING" },
"subject": { "type": "INDIVIDUAL" },
"check": {
"id": "chk_identity_123",
"name": "IDENTITY",
"displayName": "Kenyan Identity Check",
"status": "COMPLETED",
"riskLevel": "LOW",
"riskScore": 8,
"summary": "Identity verified against official identity records",
"headline": "Nothing of concern found",
"flags": [],
"displaySections": [
{
"key": "identity_records",
"title": "Identity record",
"type": "people",
"people": [{
"name": "Jane Doe",
"match": "Name match 100%",
"rows": [
{ "label": "ID number", "value": "3121****", "mono": true },
{ "label": "Citizenship", "value": "Kenyan" }
]
}]
}
],
"executedAt": "2026-10-16T08:05:12Z"
}
}| Field | Description |
|---|---|
check.status | COMPLETED — it ran. Not a verdict. |
check.riskLevel / riskScore | What it found, and a 0–100 score. |
check.summary | One line for people. |
check.headline | The short verdict to show, e.g. "Nothing of concern found". |
check.flags | Adverse findings. Empty when there are none. |
check.displaySections[] | The evidence, ready to render. See below. |
check.executedAt | When it ran. |
A high-risk result is still COMPLETED:
{
"lifecycle": { "event": "check.completed", "resource": "check", "terminal": true },
"check": {
"name": "AML_CHECK",
"status": "COMPLETED",
"riskLevel": "HIGH",
"riskScore": 85,
"summary": "Hosted verification completed with a high-risk outcome",
"flags": ["Potential sanctions or PEP match requires review"]
}
}check.failed
The check could not complete — an expired hosted session, a lookup that did not
return. riskLevel is UNKNOWN.
{
"lifecycle": { "event": "check.failed", "resource": "check", "terminal": true },
"report": { "id": "rpt_789", "status": "PROCESSING" },
"check": {
"id": "chk_aml_789",
"name": "AML_CHECK",
"status": "FAILED",
"riskLevel": "UNKNOWN",
"summary": "Hosted verification session expired before completion",
"flags": [],
"executedAt": "2026-10-16T08:16:03Z"
}
}This is not an adverse finding. Nothing was established about the subject. Retry the check or start a new hosted session — never record it as a negative result.
Rendering displaySections
A completed check carries its evidence as sections you can render without
knowing which check produced them. Every section has a key, a title and a
type.
| Type | Shape | Render as |
|---|---|---|
fields | rows[] of label and value | A label/value list. |
table | columns[] and tableRows[][] | A table. statusColumn is the index of the column holding the outcome. |
people | people[], each with name, match and rows[] | A card per person, with their details beneath. |
A row may carry mono: true (render in a monospace font) and status
(clear, and other values for outcomes you may want to colour).
{
"key": "screening_matches",
"title": "Names screened",
"type": "table",
"columns": ["Name", "List", "Score", "Outcome"],
"statusColumn": 3,
"tableRows": [["J. Doe", "PEP dataset", "85", "Review"]]
}Render the sections in the order given, and treat the labels as display text.
New section types and keys can appear as checks gain detail, so skip a type
you do not recognise rather than failing the delivery.
monitoring.alert.created
Sent when a recurring check raises an alert. It points at the report and check result rather than repeating them.
{
"alertId": "0a000190-a11c-1e00-81a1-1c9012340001",
"reportId": "0a00018c-a11a-1cc8-81a1-1a5064aa0028",
"checkResultId": "0a00018c-a11a-1cc8-81a1-1a50954b0033",
"checkName": "IDENTITY",
"alertType": "RISK_CHANGE",
"severity": "HIGH",
"title": "Monitoring alert",
"description": "A monitored check returned a new high-risk signal.",
"riskScore": 82,
"createdAt": "2026-10-09T08:15:22Z"
}| Field | Description |
|---|---|
alertId | The alert. Use it to mark the alert read or actioned. |
reportId / checkResultId | What the alert was raised against. |
checkName | Which check changed. |
alertType | Why it was raised, e.g. RISK_CHANGE. |
severity | LOW, MEDIUM, HIGH or CRITICAL. |
riskScore | The new score, 0–100. |
Fetch the report when you need the detail behind an alert.
Testing and debugging
Send a test event to exercise
your handler before real traffic arrives. It delivers test.ping to the
configured URL:
curl -X POST "https://api.verifisha.com/api/v1/webhooks/config/test" \
-H "Authorization: Bearer vrf_live_..."Then read the delivery logs, which record each attempt with the HTTP status your endpoint returned:
curl "https://api.verifisha.com/api/v1/webhooks/config/logs?page=0&size=20" \
-H "Authorization: Bearer vrf_live_..."That is the first place to look when an event seems to have been missed.
Handling redelivery
Acknowledge quickly and do the work in the background: a delivery that is not acknowledged is retried, so your endpoint can receive the same event more than once.
Make your handler idempotent by keying on X-Verifisha-Delivery, or on the
identifier the payload carries — report.id for report events, alertId for
alerts.
Handler checklist
- Verify
X-Verifisha-Signatureagainst the raw body before parsing it. - Check
X-Verifisha-Environment— a sandbox delivery must not move anything in production. - Deduplicate on
X-Verifisha-Delivery. Deliveries are retried. - Act on a check only when
lifecycle.terminalistrue. - Treat
COMPLETEDas "it ran", then apply your policy usingriskLevel,riskScoreandflags. - Treat
FAILEDas incomplete processing, not an adverse finding. - Use
report.readyandreport.failedas the source of truth for the whole report.