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

EventFires when
check.startedA check began. Hosted checks — liveness, AML screening — emit this while they wait on the subject.
check.completedA check finished running.
check.failedA check could not complete.
report.readyEvery check in the report reached a terminal state.
report.failedThe report could not be completed.
monitoring.alert.createdA recurring check raised an alert.
test.pingYou 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:

FieldMeaning
lifecycle.eventThe event name, matching X-Verifisha-Event.
lifecycle.resourcecheck for a single check, report for the whole report.
lifecycle.terminaltrue 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

HeaderValue
X-Verifisha-EventThe event name, e.g. report.ready.
X-Verifisha-DeliveryDelivery identifier. Matches the delivery log entry.
X-Verifisha-Environmentlive or sandbox.
X-Verifisha-SignatureSignature 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

FieldDescription
schemaVersionThe payload version. Log it — it is how you will know a shape changed.
environmentLIVE or SANDBOX.
workspaceIdThe workspace the report belongs to.
lifecycle.eventThe event name, matching X-Verifisha-Event.
lifecycle.resourceWhat the event is about, e.g. report.
lifecycle.terminaltrue when nothing further will arrive for this resource.
subject.typeINDIVIDUAL or BUSINESS. The subject's identity is not included.

The report

FieldDescription
report.idUse it to fetch the full record.
report.statusWhich terminal state it reached. Branch on this, not on the event name alone.
report.riskLevelAggregate band across the checks — LOW, MEDIUM, HIGH, CRITICAL, or UNKNOWN when no score could be derived.
report.compositeScoreAggregate score, 0–100. null when no score could be derived.
report.checkCountHow many checks the report ran.
report.conclusionA title and description written for people — show it, do not parse it.
report.consentStatusHow consent stood when the report ran.
report.paymentModeWho paid.
report.selfVerificationWhether the report was a workspace verifying itself.
report.createdAt / completedAtWhen the report was created, and when it reached this state.

Each check

FieldDescription
nameThe check, as named in checksRequested.
displayName / categorySafe to show in your own UI.
statusWhether the check ran: PENDING, RUNNING, COMPLETED, FAILED, SKIPPED or CANCELLED. Not what it found.
riskLevel / riskScoreLOW, MEDIUM, HIGH, CRITICAL or UNKNOWN, and a 0–100 score. This is what the check found.
summaryOne line written for people, not for parsing.
flagsAdverse findings. Empty when there are none.
evidenceDetails[]key, label and value triples backing the outcome.
executedAt / durationMsWhen 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"
  }
}
FieldDescription
check.statusCOMPLETED — it ran. Not a verdict.
check.riskLevel / riskScoreWhat it found, and a 0–100 score.
check.summaryOne line for people.
check.headlineThe short verdict to show, e.g. "Nothing of concern found".
check.flagsAdverse findings. Empty when there are none.
check.displaySections[]The evidence, ready to render. See below.
check.executedAtWhen 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.

TypeShapeRender as
fieldsrows[] of label and valueA label/value list.
tablecolumns[] and tableRows[][]A table. statusColumn is the index of the column holding the outcome.
peoplepeople[], 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"
}
FieldDescription
alertIdThe alert. Use it to mark the alert read or actioned.
reportId / checkResultIdWhat the alert was raised against.
checkNameWhich check changed.
alertTypeWhy it was raised, e.g. RISK_CHANGE.
severityLOW, MEDIUM, HIGH or CRITICAL.
riskScoreThe 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

  1. Verify X-Verifisha-Signature against the raw body before parsing it.
  2. Check X-Verifisha-Environment — a sandbox delivery must not move anything in production.
  3. Deduplicate on X-Verifisha-Delivery. Deliveries are retried.
  4. Act on a check only when lifecycle.terminal is true.
  5. Treat COMPLETED as "it ran", then apply your policy using riskLevel, riskScore and flags.
  6. Treat FAILED as incomplete processing, not an adverse finding.
  7. Use report.ready and report.failed as the source of truth for the whole report.

On this page