Failure Payload

When a verification step fails, Zyphe sends a webhook with "event": "FAILED" and the step-specific failure data. The status field inside the step data will indicate the reason for failure.

Document Verification Failure

{
  "resultId": "7fd1c306-7830-4261-b372-181f742055ef",
  "event": "FAILED",
  "data": {
    "dv": {
      "version": 0,
      "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
      "verificationRequestId": "d72b7afc-6841-4478-9d21-3e8dd3d26695",
      "flowId": "2d8285d7-f4ba-42df-ab3f-681d9870d37a",
      "flowStepId": "03559a0f-be8e-4ab7-964d-1ff4745d92a4",
      "createdAt": "2025-04-25T10:05:51.851407Z",
      "customData": {},
      "status": "FAILED",
      "reasons": ["DOCUMENT_EXPIRED"],
      "documentId": "abcc8e8b7b354cb9978c40b66de2bae3",
      "documentType": "Driving License",
      "class": "web-mobile",
      "platform": "iOS",
      "browser": "Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X)...",
      "scoreBiometricSelfie": 99,
      "errorMessage": null,
      "processAdditionalData": {},
      "identityEmail": "user@example.com"
    }
  },
  "custom": {},
  "flowStatus": "FAILED"
}

Key Fields

• event: "FAILED" — indicates the verification step did not pass.
• status: "FAILED" — the document verification result status.
• reasons: An array of strings describing why the verification failed (e.g., "DOCUMENT_EXPIRED", "LOW_QUALITY", "UNDERAGE").
• errorMessage: An optional error message with additional context.
• flowStatus: The overall status of the flow after this step.

Proof of Address Failure

{
  "resultId": "0e66460a-c189-48a0-8a1a-a3f846c992e5",
  "event": "FAILED",
  "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": "FAILED",
      "reason": "Document is older than the maximum allowed age",
      "documentId": "e04a00e6-ccf9-4593-ab86-4b2c01f3bb95",
      "documentType": "UTILITY_BILL",
      "identityEmail": "user@example.com"
    }
  },
  "custom": {},
  "flowStatus": "FAILED"
}

Key Fields

• reason: A string describing why the proof of address failed.

Form Step Failure

{
  "resultId": "b2c3d4e5-6789-0abc-def1-234567890abc",
  "event": "FAILED",
  "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": "FAILED",
      "reason": "Required fields missing",
      "sections": [],
      "formId": null,
      "formName": "Customer Onboarding Form",
      "identityEmail": "user@example.com",
      "errorMessage": null
    }
  },
  "custom": {},
  "flowStatus": "FAILED"
}

Error-Only Failure (No Result Data)

In some cases, a step may fail before a result can be created (e.g., processing errors). In these cases, the step data will contain minimal information:

{
  "resultId": "7fd1c306-7830-4261-b372-181f742055ef",
  "event": "FAILED",
  "data": {
    "dv": {
      "version": 0,
      "id": "00000000-0000-0000-0000-000000000000",
      "verificationRequestId": "d72b7afc-6841-4478-9d21-3e8dd3d26695",
      "flowId": "2d8285d7-f4ba-42df-ab3f-681d9870d37a",
      "flowStepId": "03559a0f-be8e-4ab7-964d-1ff4745d92a4",
      "createdAt": "2025-04-25T10:05:51.851407Z",
      "customData": {},
      "status": "",
      "reasons": [],
      "documentId": "",
      "documentType": "",
      "class": null,
      "platform": null,
      "browser": null,
      "scoreBiometricSelfie": null,
      "errorMessage": "Processing failed: timeout exceeded",
      "processAdditionalData": null,
      "identityEmail": "user@example.com"
    }
  },
  "custom": {},
  "flowStatus": "FAILED"
}

In this scenario, the errorMessage field provides details about what went wrong.

Review Events

When a result requires manual review, the event is "REVIEW" instead of "FAILED":

{
  "resultId": "7fd1c306-7830-4261-b372-181f742055ef",
  "event": "REVIEW",
  "data": {
    "dv": {
      "...": "same structure as above"
    }
  },
  "custom": {},
  "flowStatus": "REQUIRES_MANUAL_REVIEW"
}

The "REVIEW" event is sent when the result status is REQUIRES_MANUAL_REVIEW.