Skip to main content

Webhook Payload

Top-Level Structure​

Every webhook call includes the following top-level fields:

{
  "resultId": "936f35a8-4921-430e-b016-15be48968886",
  "event": "COMPLETED",
  "data": {
    "<type>": {
      // ... step-specific data
    }
  },
  "custom": {},
  "flowStatus": "COMPLETED"
}

Top-Level Fields​

  • resultId: The flow result identifier.
  • event: The outcome of the verification step. Possible values:
    • COMPLETED — The step passed successfully.
    • FAILED — The step failed.
    • REVIEW — The step requires manual review.
    • REJECTED — The step was rejected after review.
  • data: Contains the step-specific result. Only one key is present per webhook, corresponding to the step type (dv, poa, form, phone, wallet, spid).
  • custom: Custom data associated with the flow result.
  • flowStatus: The overall status of the verification flow. Possible values: COMPLETED, FAILED, CANCELLED, REQUIRES_MANUAL_REVIEW, REJECTED.

Document Verification​

{
  "resultId": "936f35a8-4921-430e-b016-15be48968886",
  "event": "COMPLETED",
  "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": null,
      "platform": null,
      "browser": null,
      "scoreBiometricSelfie": 99,
      "errorMessage": null,
      "processAdditionalData": {},
      "identityEmail": "applicant01@example.com"
    }
  },
  "custom": null
}

Document Verification Fields​

  • version: The version of the document verification processor.
  • id: The DvResult identifier.
  • verificationRequestId: The verification request that generated this result.
  • flowId: The flow identifier.
  • flowStepId: The flow step identifier.
  • createdAt: Timestamp when the result was created.
  • customData: Custom parameters collected from URL query parameters.
  • status: Status of the document verification. Possible values: PASSED, FAILED, PARTIAL, REQUIRES_MANUAL_REVIEW.
  • reasons: An array of strings describing failure or warning reasons (e.g., "DOCUMENT_EXPIRED", "LOW_QUALITY", "UNDERAGE"). Empty when the verification passes.
  • documentType: The type of document used for verification (e.g., "Driving License", "Passport", "ID Card").
  • documentId: Identifier of the document recorded in the user's personal storage.
  • scoreBiometricSelfie: The portrait match score from the Liveness Verification step. Represents the similarity between the live selfie and the portrait extracted from the identity document.
  • errorMessage: An optional error message with additional context.
  • processAdditionalData: Additional data collected during the verification process.
  • identityEmail: The email address of the identity that went through the verification.

Proof of Address​

{
  "resultId": "0e66460a-c189-48a0-8a1a-a3f846c992e5",
  "event": "COMPLETED",
  "data": {
    "poa": {
      "version": 0,
      "id": "cdf75b57-a1d8-4c1c-8718-c367206707b4",
      "verificationRequestId": "19234ab9-33df-4fae-a636-361f0f5ca607",
      "flowId": "2d8285d7-f4ba-42df-ab3f-681d9870d37a",
      "flowStepId": "56efd673-24d1-455b-a5b9-8ddf02a9b5f2",
      "createdAt": "2025-04-25T19:32:25.799246492Z",
      "customData": {},
      "status": "PASSED",
      "reason": null,
      "documentId": "e04a00e6-ccf9-4593-ab86-4b2c01f3bb95",
      "documentType": "PAY_SLIP",
      "identityEmail": "applicant01@example.com"
    }
  },
  "custom": {}
}

Proof of Address Fields​

  • version: The version of the proof of address processor.
  • id: The PoaResult identifier.
  • verificationRequestId: The verification request that generated this result.
  • flowId: The flow identifier.
  • flowStepId: The flow step identifier.
  • createdAt: Timestamp when the result was created.
  • customData: Custom parameters collected from URL query parameters.
  • status: Status of the proof of address verification (PASSED or FAILED).
  • reason: Reason for failure (null when passed).
  • documentType: Type of document used (e.g., "PAY_SLIP", "UTILITY_BILL", "BANK_STATEMENT").
  • documentId: Identifier of the document recorded in the user's personal storage.
  • identityEmail: The email address of the identity that went through the verification.

Form​

{
  "resultId": "b2c3d4e5-6789-0abc-def1-234567890abc",
  "event": "COMPLETED",
  "data": {
    "form": {
      "version": 0,
      "id": "f8e7d6c5-4321-8765-09ba-fedcba987654",
      "verificationRequestId": "c2d3e4f5-6789-01bc-def1-23456789abcd",
      "flowId": "2d8285d7-f4ba-42df-ab3f-681d9870d37a",
      "flowStepId": "d3e4f5g6-7890-12cd-ef12-3456789abcde",
      "createdAt": "2025-04-25T19:35:30.123456789Z",
      "customData": {},
      "status": "PASSED",
      "reason": null,
      "sections": [
        {
          "name": "Personal Information",
          "items": [
            { "name": "fullName", "value": "John Doe" },
            { "name": "dateOfBirth", "value": "1990-01-15" }
          ]
        }
      ],
      "formId": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
      "formName": "Customer Onboarding Form",
      "identityEmail": "applicant01@example.com",
      "errorMessage": null
    }
  },
  "custom": null
}

Form Fields​

  • version: The version of the form processor.
  • id: The FormResult identifier.
  • verificationRequestId: The verification request that generated this result.
  • flowId: The flow identifier.
  • flowStepId: The flow step identifier.
  • createdAt: Timestamp when the result was created.
  • customData: Custom parameters collected from URL query parameters.
  • status: Status of the form step (PASSED or FAILED).
  • reason: Reason for failure (null when passed).
  • sections: The submitted form data, structured by sections and items.
  • formId: Identifier of the form definition.
  • formName: The name of the form.
  • identityEmail: The email address of the identity.
  • errorMessage: An optional error message.

Phone Verification​

{
  "resultId": "a7b8c9d0-1234-5678-90ab-cdef12345678",
  "event": "COMPLETED",
  "data": {
    "phone": {
      "version": 0,
      "id": "f8e7d6c5-4321-8765-09ba-fedcba987654",
      "verificationRequestId": "b1c2d3e4-5678-90ab-cdef-1234567890ab",
      "flowId": "2d8285d7-f4ba-42df-ab3f-681d9870d37a",
      "flowStepId": "c3d4e5f6-7890-abcd-ef12-34567890abcd",
      "createdAt": "2025-04-25T19:35:30.123456789Z",
      "customData": {},
      "status": "PASSED",
      "reason": null,
      "errorMessage": null,
      "identityEmail": "applicant01@example.com",
      "phoneNumberLast4": "1234"
    }
  },
  "custom": null
}

Phone Verification Fields​

  • version: The version of the phone verification processor.
  • id: The PhoneResult identifier.
  • verificationRequestId: The verification request that generated this result.
  • flowId: The flow identifier.
  • flowStepId: The flow step identifier.
  • createdAt: Timestamp when the result was created.
  • customData: Custom parameters collected from URL query parameters.
  • status: Status of the phone verification (PASSED or FAILED).
  • reason: Reason for failure (null when passed).
  • errorMessage: An optional error message.
  • identityEmail: The email address of the identity.
  • phoneNumberLast4: The last 4 digits of the verified phone number.
Privacy & Security

For privacy and security reasons, the full phone number is not included in the webhook payload. The phone number is stored as a SHA-256 hash in the database, with only the last 4 digits available in plain text for reference.

Wallet Verification​

{
  "resultId": "a7b8c9d0-1234-5678-90ab-cdef12345678",
  "event": "COMPLETED",
  "data": {
    "wallet": {
      "version": 0,
      "id": "b1c2d3e4-5678-90ab-cdef-123456789012",
      "verificationRequestId": "c2d3e4f5-6789-01bc-def1-23456789abcd",
      "flowId": "d3e4f5g6-7890-12cd-ef12-3456789abcde",
      "flowStepId": "e4f5g6h7-8901-23de-f123-456789abcdef",
      "createdAt": "2025-10-17T10:15:30.123456789Z",
      "customData": {},
      "status": "PASSED",
      "message": "example.com wants you to sign in with your Ethereum account...",
      "reason": null,
      "signature": "0x1234567890abcdef...",
      "walletAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
      "walletChain": "ETHEREUM",
      "identityEmail": "applicant01@example.com",
      "errorMessage": null
    }
  },
  "custom": null
}

Wallet Verification Fields​

  • version: The version of the wallet verification processor.
  • id: The WalletResult identifier.
  • verificationRequestId: The verification request that generated this result.
  • flowId: The flow identifier.
  • flowStepId: The flow step identifier.
  • createdAt: Timestamp when the result was created.
  • customData: Custom parameters collected from URL query parameters.
  • status: Status of the wallet verification (PASSED or FAILED).
  • message: The SIWX (Sign-In With X) message that was signed by the user.
  • reason: Reason for failure (null when passed).
  • signature: The cryptographic signature produced by signing the message.
  • walletAddress: The cryptocurrency wallet address that was verified.
  • walletChain: The blockchain network used (e.g., ETHEREUM, SOLANA, ETHEREUM_TESTNET, SOLANA_TESTNET).
  • identityEmail: The email address of the identity.
  • errorMessage: An optional error message.

SPID / CIE​

{
  "resultId": "c3d4e5f6-7890-abcd-ef12-34567890abcd",
  "event": "COMPLETED",
  "data": {
    "spid": {
      "version": 0,
      "id": "d4e5f6g7-8901-bcde-f123-456789abcdef",
      "verificationRequestId": "e5f6g7h8-9012-cdef-0123-56789abcdef0",
      "flowId": "2d8285d7-f4ba-42df-ab3f-681d9870d37a",
      "flowStepId": "f6g7h8i9-0123-def0-1234-6789abcdef01",
      "createdAt": "2025-04-25T19:40:00.123456789Z",
      "customData": {},
      "status": "PASSED",
      "reason": null,
      "errorMessage": null,
      "identityEmail": "applicant01@example.com",
      "userInfo": {
        "id": "TINIT-ABCDEF12G34H567I",
        "email": "user@pec.it",
        "mobilePhone": "+391234567890",
        "username": null,
        "firstName": "Mario",
        "digitalAddress": null,
        "spidCode": "ABCDEF12G34H567I",
        "dateOfBirth": "1990-01-15",
        "gender": "M",
        "fiscalNumber": "RSSMRA90A15H501Z",
        "fullName": "Mario Rossi",
        "placeOfBirth": "Roma",
        "countryOfBirth": "IT",
        "lastName": "Rossi",
        "address": "Via Roma 1, 00100 Roma RM",
        "companyName": null,
        "registeredOffice": null,
        "companyVatNumber": null
      }
    }
  },
  "custom": null
}

SPID / CIE Fields​

  • version: The version of the SPID processor.
  • id: The SpidResult identifier.
  • verificationRequestId: The verification request that generated this result.
  • flowId: The flow identifier.
  • flowStepId: The flow step identifier.
  • createdAt: Timestamp when the result was created.
  • customData: Custom parameters collected from URL query parameters.
  • status: Status of the SPID verification (PASSED or FAILED).
  • reason: Reason for failure (null when passed).
  • errorMessage: An optional error message.
  • identityEmail: The email address of the identity.
  • userInfo: The user's personal data retrieved from the Italian digital identity provider. Includes:
    • firstName, lastName, fullName — Name information
    • fiscalNumber — Italian fiscal code (codice fiscale)
    • dateOfBirth, gender — Personal details
    • placeOfBirth, countryOfBirth — Birth information
    • address — Residential address
    • email, mobilePhone — Contact details
    • spidCode — The SPID identifier code
    • companyName, registeredOffice, companyVatNumber — Business details (for business SPID accounts)

Extended Webhook (Document Verification)​

When the Extended Webhook option is enabled in your flow settings, document verification webhooks include an additional additionalData field with extracted personal data from the identity document.

{
  "resultId": "936f35a8-4921-430e-b016-15be48968886",
  "event": "COMPLETED",
  "data": {
    "dv": {
      "version": 0,
      "id": "d65fa9a0-596e-4d7e-afd1-59a23bfb5a74",
      "verificationRequestId": "cf52e18e-28d1-4a2f-8304-c04ef5a75d0f",
      "...": "same fields as standard DV payload"
    },
    "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://..."
      }
    }
  },
  "custom": null,
  "flowStatus": "COMPLETED"
}

Extended Data Fields​

  • firstName: First name extracted from the document.
  • lastName: Last name extracted from the document.
  • dateOfBirth: Date of birth extracted from the document.
  • documentNumber: The document's serial/identification number.
  • issuingState: The country that issued the document (ISO 3166 code).
  • expiryDate: The document's expiry date (null if not present on the document).
  • issuingDate: The date the document was issued (null if not present).
  • issuingAuthority: The authority that issued the document.
  • personalNumber: Personal identification number (if present on the document).
  • documentClassCode: The document class code.
  • selfie: The liveness selfie image, if available:
    • contentType: The MIME type (e.g., "image/jpeg").
    • presignedUrl: A time-limited URL to download the selfie image.
Enabling Extended Webhooks

To enable the extended webhook format, configure the Extended Webhook option in your flow settings via the Zyphe Dashboard. Contact support if you need assistance.

KYB (Know Your Business)​

KYB verification results are not delivered via webhook. KYB results — including moderation status, UBO definitions, and director information — are available exclusively through the Zyphe Dashboard and API.

info

To retrieve KYB results programmatically, use the flow results API endpoints. Webhook notifications are not sent for KYB step completions.

AML (Anti-Money Laundering)​

AML screening results are not delivered via webhook. AML results — including risk scores, risk levels, entity matches, and sanctions data — are available exclusively through the Zyphe Dashboard and API.

info

To retrieve AML results programmatically, use the flow results API endpoints. Webhook notifications are not sent for AML screenings.

Other Events​

Document Expired​

Triggered whenever a document attached to a verified user expires. The check runs daily.

{
  "resultId": "",
  "event": "NOTIFICATION",
  "data": {
    "eventData": {
      "version": 0,
      "type": "DOCUMENT_EXPIRED",
      "flowResultId": "d65fa9a0-596e-4d7e-afd1-59a23bfb5a74",
      "verificationRequestId": "cf52e18e-28d1-4a2f-8304-c04ef5a75d0f",
      "flowId": "2d8285d7-f4ba-42df-ab3f-681d9870d37a",
      "flowStepId": "03559a0f-be8e-4ab7-964d-1ff4745d92a4",
      "expiryDate": "2025-04-25T00:00:00.00Z",
      "customData": {},
      "documentId": "d41bc0ea-3b5c-4342-a1ae-a46dd0a770f8",
      "documentType": "Driving License",
      "identityEmail": "applicant01@example.com"
    }
  },
  "custom": {}
}

Event Data Fields​

  • type: Type of the notification event (DOCUMENT_EXPIRED).
  • flowResultId: The flow result associated with the expired document.
  • verificationRequestId: The original verification request identifier.
  • flowId: The flow identifier.
  • flowStepId: The flow step identifier.
  • expiryDate: The expiration date of the document.
  • customData: Custom parameters from the original verification.
  • documentType: Type of the document.
  • documentId: Identifier of the document in the user's personal storage.
  • identityEmail: The email address of the identity.