Backwards Compatibility

Legacy Webhook Format

For organizations migrating from an earlier version of the Zyphe platform, a legacy kyc payload format is available for document verification (DV) webhooks. This legacy format is opt-in and must be explicitly enabled for your organization.

warning

The legacy kyc format is provided only for backward compatibility during migration. New integrations should use the current dv payload format described in the Webhook Payload page.

Enabling the Legacy Format

Contact the Zyphe support team to enable the legacy webhook format for your organization. When enabled, document verification webhooks will include both the current dv field and the legacy kyc field in the data object:

{
  "resultId": "7fd1c306-7830-4261-b372-181f742055ef",
  "event": "COMPLETED",
  "data": {
    "kyc": {
      "id": "7fd1c306-7830-4261-b372-181f742055ef",
      "kycInquiryId": "d72b7afc-6841-4478-9d21-3e8dd3d26695",
      "createdAt": "2025-04-25T10:05:51.851407Z",
      "tenantId": "",
      "customData": {},
      "status": "PASSED",
      "documentId": "abcc8e8b7b354cb9978c40b66de2bae3",
      "documentType": "Driving License",
      "class": "web-mobile",
      "platform": "iOS",
      "browser": "Mozilla/5.0 ...",
      "scoreDocumentTotal": 1,
      "scoreBiometricLifeProof": 1,
      "scoreBiometricSelfie": 99,
      "scoreBiometricPhotoId": 1,
      "scoreBiometricDuplicateAttack": 1,
      "processCode": "ProcessCompleted",
      "processType": "info",
      "processMessage": null,
      "processAdditionalData": {},
      "identityId": "user@example.com"
    },
    "dv": {
      "version": 0,
      "id": "d65fa9a0-596e-4d7e-afd1-59a23bfb5a74",
      "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": "PASSED",
      "reasons": [],
      "documentId": "abcc8e8b7b354cb9978c40b66de2bae3",
      "documentType": "Driving License",
      "class": "web-mobile",
      "platform": "iOS",
      "browser": "Mozilla/5.0 ...",
      "scoreBiometricSelfie": 99,
      "errorMessage": null,
      "processAdditionalData": {},
      "identityEmail": "user@example.com"
    }
  },
  "custom": {},
  "flowStatus": "COMPLETED"
}

Key Differences

Field	Legacy (kyc)	Current (dv)
Identifier	kycInquiryId	verificationRequestId
Identity	identityId (zid)	identityEmail (email)
Tenant	tenantId	Not included
Scores	Multiple score fields (scoreDocumentTotal, scoreBiometricLifeProof, etc.)	scoreBiometricSelfie only
Failure info	processType, processCode, processMessage	reasons array, errorMessage
Flow references	Not included	flowId, flowStepId

Migration Guide

1. Start consuming the dv field from the webhook data object.
2. Update your field mappings according to the table above.
3. Once fully migrated, contact support to disable the legacy format.

info

The legacy kyc field is only included for document verification webhooks. Other step types (PoA, Form, Phone, Wallet, SPID) do not have a legacy format.