Webhook Payload

This page documents the objects carried by standard result webhooks and lifecycle notifications. The outer HTTP and envelope contract is defined once in Receiving Webhooks.

Standard result fields

Most result objects under data share these fields:

Field	Meaning
`version`	Payload schema version.
`id`	Identifier of the step result. It may contain a default value when processing failed before a result was created.
`verificationRequestId`	Verification request that produced the result.
`flowId`	Flow identifier.
`flowStepId`	Flow-step identifier.
`createdAt`	ISO 8601 timestamp associated with the request or result.
`customData`	Custom values attached to the verification request. See Custom Fields.
`status`	Status of the individual result. Do not confuse it with top-level `flowStatus`.
`identityEmail`	Email of the verified identity, when available.
`reason` / `reasons`	Structured failure or review context, depending on result type.
`errorMessage`	Optional processing diagnostic, when supported by the result type.

The primary result key is the non-null value among dv, poa, form, spid, phone, wallet, kyb, aml, and geolocation. Other keys may be absent or null, depending on the serializer. Extended and legacy DV configurations can add companion values beside dv.

Document Verification (`data.dv`)

{
  "version": 0,
  "id": "d65fa9a0-596e-4d7e-afd1-59a23bfb5a74",
  "verificationRequestId": "cf52e18e-28d1-4a2f-8304-c04ef5a75d0f",
  "flowId": "2d8285d7-f4ba-42df-ab3f-681d9870d37a",
  "flowStepId": "03559a0f-be8e-4ab7-964d-1ff4745d92a4",
  "createdAt": "2025-04-25T19:32:14.558006634Z",
  "customData": {},
  "status": "PASSED",
  "reasons": [],
  "documentId": "d41bc0ea-3b5c-4342-a1ae-a46dd0a770f8",
  "documentType": "Driving License",
  "class": "web-mobile",
  "platform": "iOS",
  "browser": "Mozilla/5.0 ...",
  "scoreBiometricSelfie": 99,
  "errorMessage": null,
  "processAdditionalData": {},
  "identityEmail": "applicant01@example.com"
}

DV-specific field	Meaning
`reasons`	Structured reasons such as `DOCUMENT_EXPIRED`, `LOW_QUALITY`, or `UNDERAGE`. Empty when no reason is reported.
`documentId`	Identifier of the document stored for this result.
`documentType`	Human-readable document type.
`class`, `platform`, `browser`	Optional client context captured during verification.
`scoreBiometricSelfie`	Optional portrait-match percentage.
`processAdditionalData`	Additional processor output, when available.

Extended document verification (`data.additionalData`)

When Extended Webhook is enabled, additionalData is a sibling of dv inside data:

{
  "data": {
    "dv": {
      "id": "d65fa9a0-596e-4d7e-afd1-59a23bfb5a74",
      "status": "PASSED"
    },
    "additionalData": {
      "firstName": "John",
      "lastName": "Doe",
      "dateOfBirth": "1990-01-15",
      "documentNumber": "AB1234567",
      "issuingState": "GBR",
      "expiryDate": "2030-12-31",
      "issuingDate": "2020-01-01",
      "issuingAuthority": "DVLA",
      "personalNumber": "",
      "documentClassCode": "DL",
      "selfie": {
        "contentType": "image/jpeg",
        "presignedUrl": "https://..."
      }
    }
  }
}

selfie.presignedUrl is time-limited. Download it only when needed and apply the same access controls used for other identity data.

The legacy data.kyc companion is documented in Backwards Compatibility.

Proof of Address (`data.poa`)

In addition to the common result fields, proof-of-address results contain:

Field	Meaning
`reason`	Optional failure reason.
`documentId`	Identifier of the uploaded address document.
`documentType`	Document type, such as `PAY_SLIP`, `UTILITY_BILL`, or `BANK_STATEMENT`.

{
  "status": "PASSED",
  "reason": null,
  "documentId": "e04a00e6-ccf9-4593-ab86-4b2c01f3bb95",
  "documentType": "UTILITY_BILL"
}

Form (`data.form`)

Field	Meaning
`reason`	Optional failure reason.
`sections`	Submitted answers grouped by form section.
`formId`	Identifier of the form definition, when available.
`formName`	Name of the form.

{
  "status": "PASSED",
  "reason": null,
  "sections": [
    {
      "name": "Personal Information",
      "items": [{ "name": "fullName", "value": "John Doe" }]
    }
  ],
  "formId": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
  "formName": "Customer Onboarding Form",
  "errorMessage": null
}

Phone Verification (`data.phone`)

Phone results include reason, errorMessage, and phoneNumberLast4 in addition to the common fields.

{
  "status": "PASSED",
  "reason": null,
  "errorMessage": null,
  "phoneNumberLast4": "1234"
}

:::info Phone-number privacy The full phone number is not included in the webhook. Zyphe stores a SHA-256 hash and exposes only the final four digits in this result. :::

Wallet Verification (`data.wallet`)

Field	Meaning
`message`	SIWX message signed by the user.
`signature`	Signature produced by the wallet.
`walletAddress`	Verified wallet address.
`walletChain`	Network used, such as `ETHEREUM`, `SOLANA`, or their testnet variants.
`reason`, `errorMessage`	Optional failure context.

{
  "status": "PASSED",
  "message": "example.com wants you to sign in with your Ethereum account...",
  "signature": "0x1234567890abcdef...",
  "walletAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
  "walletChain": "ETHEREUM",
  "reason": null,
  "errorMessage": null
}

SPID / CIE (`data.spid`)

SPID/CIE results include optional reason, errorMessage, and userInfo. The userInfo object can contain:

Name and identity attributes: firstName, lastName, fullName, fiscalNumber, dateOfBirth, gender
Birth and address attributes: placeOfBirth, countryOfBirth, address
Contact attributes: email, mobilePhone, digitalAddress
Provider attributes: id, username, spidCode
Business-account attributes: companyName, registeredOffice, companyVatNumber

Fields depend on the identity provider and may be null.

Geolocation (`data.geolocation`)

{
  "status": "PASSED",
  "reason": null,
  "errorMessage": null,
  "country": "IT",
  "ipAddress": "203.0.113.10",
  "deviceFingerprint": "device-fingerprint",
  "vpn": false,
  "blacklistedIp": false
}

Field	Meaning
`country`	Resolved country, when available.
`ipAddress`	IP address evaluated for the result.
`deviceFingerprint`	Device fingerprint associated with the proof.
`vpn`	Whether VPN usage was detected.
`blacklistedIp`	Whether the IP matched a blacklist.

KYB (`data.kyb`)

KYB results are delivered using the standard envelope. They include the common result fields plus:

Field	Meaning
`businessInformation`	Submitted and verified business information.
`documentUploads`	KYB document-upload state and metadata.
`uboDefinitions`	Ultimate Beneficial Owner definitions and verification state.
`directorDefinitions`	Director definitions and verification state.
`pepAndSanctionsStatus`	Consolidated PEP and sanctions state.
`nextAction`	Next action required by the KYB workflow, when any.
`assignedToIdentityId`	Reviewer assigned to the result, when any.
`fundedAt`	Funding timestamp, when applicable.
`report`	Generated report or report reference, when available.

{
  "status": "REQUIRES_MANUAL_REVIEW",
  "reason": null,
  "errorMessage": null,
  "businessInformation": {},
  "documentUploads": [],
  "uboDefinitions": [],
  "directorDefinitions": [],
  "pepAndSanctionsStatus": null,
  "nextAction": null
}

AML (`data.aml`)

AML deliveries represent produced results, scheduled refreshes, and moderation changes. Top-level event and inner updateKind use PRODUCED, REFRESHED, or MODERATED.

{
  "event": "PRODUCED",
  "data": {
    "aml": {
      "version": 0,
      "id": "e5f6a7b8-9012-3456-7890-abcdef123456",
      "verificationRequestId": "cf52e18e-28d1-4a2f-8304-c04ef5a75d0f",
      "flowId": "2d8285d7-f4ba-42df-ab3f-681d9870d37a",
      "flowStepId": "03559a0f-be8e-4ab7-964d-1ff4745d92a4",
      "createdAt": "2026-07-14T10:15:30Z",
      "updateKind": "PRODUCED",
      "status": "PENDING",
      "subjectType": "PERSON",
      "hasPep": false,
      "hasSanctions": false,
      "riskScorePercent": 12
    }
  }
}

Field	Meaning
`updateKind`	Why this webhook was emitted: `PRODUCED`, `REFRESHED`, or `MODERATED`.
`status`	Moderation state: `PENDING`, `APPROVED`, `REJECTED`, or `ESCALATED`.
`subjectType`	Screened subject type, such as `PERSON` or `COMPANY`.
`hasPep`	Whether PEP matches are present.
`hasSanctions`	Whether sanctions matches are present.
`riskScorePercent`	Optional risk score from 0 to 100.

Notification events

Notification webhooks use top-level eventData, not data, and omit flowStatus. See the full envelope in Receiving Webhooks.

`DOCUMENT_EXPIRED`

{
  "version": 0,
  "type": "DOCUMENT_EXPIRED",
  "flowResultId": "936f35a8-4921-430e-b016-15be48968886",
  "verificationRequestId": "cf52e18e-28d1-4a2f-8304-c04ef5a75d0f",
  "flowId": "2d8285d7-f4ba-42df-ab3f-681d9870d37a",
  "flowStepId": "03559a0f-be8e-4ab7-964d-1ff4745d92a4",
  "expiryDate": "2025-04-25",
  "customData": {},
  "documentId": "d41bc0ea-3b5c-4342-a1ae-a46dd0a770f8",
  "documentType": "Driving License",
  "identityEmail": "applicant01@example.com"
}

`KYC_RESULT_EXPIRED`

Field	Meaning
`flowResultId`	Expired flow-result identifier.
`flowId`	Associated flow.
`identityId`	Identity associated with the expired KYC result.
`dvResultId`	Document-verification result that expired.
`identityEmail`	Identity email, when available.

`FLOW_RISK_REEVALUATED`

Field	Meaning
`flowResultId`	Re-evaluated flow result.
`scoreBefore`, `scoreAfter`	Previous and current composed scores. Either may be `null`.
`statusBefore`, `statusAfter`	Previous and current flow statuses.

Use this event to refresh downstream decisions when AML moderation, scheduled AML refreshes, manual review, or administrative scoring changes the composed risk result.

Standard result fields​

Document Verification (data.dv)​

Extended document verification (data.additionalData)​

Proof of Address (data.poa)​

Form (data.form)​

Phone Verification (data.phone)​

Wallet Verification (data.wallet)​

SPID / CIE (data.spid)​

Geolocation (data.geolocation)​

KYB (data.kyb)​

AML (data.aml)​

Notification events​

DOCUMENT_EXPIRED​

KYC_RESULT_EXPIRED​

FLOW_RISK_REEVALUATED​