Backwards Compatibility

Legacy document-verification payload

Organizations migrating from an earlier Zyphe integration can opt in to the legacy data.kyc object. New integrations should consume the current data.dv object documented in Webhook Payload.

:::warning Migration only The legacy format is disabled by default and is available only for document-verification webhooks. Contact Zyphe support to enable or disable it for your organization. :::

When enabled, the same webhook contains both representations:

{
  "data": {
    "kyc": {
      "kycInquiryId": "d72b7afc-6841-4478-9d21-3e8dd3d26695",
      "identityId": "zid:example",
      "status": "PASSED",
      "processCode": "ProcessCompleted",
      "processType": "info",
      "processMessage": null
    },
    "dv": {
      "verificationRequestId": "d72b7afc-6841-4478-9d21-3e8dd3d26695",
      "flowId": "2d8285d7-f4ba-42df-ab3f-681d9870d37a",
      "flowStepId": "03559a0f-be8e-4ab7-964d-1ff4745d92a4",
      "identityEmail": "user@example.com",
      "status": "PASSED",
      "reasons": [],
      "errorMessage": null
    }
  }
}

Key differences

Concept	Legacy kyc	Current dv
Verification request	kycInquiryId	verificationRequestId
Identity	identityId	identityEmail
Flow references	Not included	flowId, flowStepId
Scores	Multiple legacy score fields	scoreBiometricSelfie
Failure details	processType, processCode, processMessage	reasons[], errorMessage
Tenant	tenantId	Not included

Migration

1. Read data.dv whenever it is present.
2. Update field mappings using the table above.
3. Test success, failure, and review events without reading data.kyc.
4. Contact support to disable the legacy format.

The outer webhook envelope is unchanged and is documented in Receiving Webhooks.