Skip to main content

Webhook Integration

This documentation will guide you through the integration process of webhooks provided by Zyphe.

Prerequisites​

Ensure that you have created a Flow in the Zyphe Dashboard, with your webhook URL configured.

Integration Steps​

Follow the steps below to integrate webhooks into your application:

  1. Register the webhook URL Configure your webhook URL in the Flow settings via the Zyphe Dashboard.
  2. Create a link Create a link on your website that directs to your Flow link. You can copy the link from the Zyphe Dashboard.
  3. User Verification The user clicks the link on your website and is redirected to the Zyphe platform.
  4. Zyphe sends results to your webhook Once a verification step is completed, Zyphe sends the result via a POST request with a JSON payload to your webhook URL.

Payload Structure​

Every webhook payload follows this top-level structure:

{
  "resultId": "f49d3a83-3dac-464a-b97a-bd8f7f1fa9b9",
  "event": "COMPLETED",
  "data": {
    "<type>": {
      // ... step-specific result data
    }
  },
  "custom": {},
  "flowStatus": "COMPLETED"
}
  • resultId — The flow result identifier.
  • event — The outcome of the verification step. Possible values: COMPLETED, FAILED, REVIEW, REJECTED.
  • data — Contains the result for the specific step type. The key corresponds to the step type: dv, poa, form, phone, wallet, or spid. Only one key is present per webhook call.
  • custom — Custom data associated with the flow result (see Custom Fields).
  • flowStatus — The overall status of the flow (e.g., COMPLETED, FAILED, REQUIRES_MANUAL_REVIEW).

Example: Document Verification Success​

{
  "resultId": "f49d3a83-3dac-464a-b97a-bd8f7f1fa9b9",
  "event": "COMPLETED",
  "data": {
    "dv": {
      "version": 0,
      "id": "d65fa9a0-596e-4d7e-afd1-59a23bfb5a74",
      "verificationRequestId": "e0da16b2-bebc-46ee-aa23-3d92a4dc818e",
      "flowId": "2d8285d7-f4ba-42df-ab3f-681d9870d37a",
      "flowStepId": "03559a0f-be8e-4ab7-964d-1ff4745d92a4",
      "createdAt": "2025-04-25T19:32:14.558006634Z",
      "customData": {},
      "status": "PASSED",
      "reasons": [],
      "documentId": "f915626947e64baf9a1454c6e662ecd1",
      "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": "COMPLETED"
}

Example: 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", "LOW_QUALITY"],
      "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"
}

For full details on all step-type payloads (DV, PoA, Form, Phone, Wallet, SPID), see the Webhook Payload page.

By following these integration steps, you can receive real-time verification results via webhook. This allows you to update your systems automatically as users complete verification flows on the Zyphe platform.