Backwards Compatibility

Two independent things are called "legacy" around webhooks. Do not confuse them:

Concept	What it is	Where it is documented
payloadVersion: "LEGACY_V1"	The pre-registry envelope: the payload shape and the strict HTTP-200 rule an endpoint receives	Payload Versions
The legacy data.kyc object	An opt-in document-verification compatibility field, delivered beside data.dv	This page

An endpoint can be LEGACY_V1 without the kyc object, and vice versa.

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.

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.

Endpoints created after the migration

Both the legacy kyc object and the extended DV payload were organization-wide settings. When per-flow webhook URLs were converted into webhook endpoints, those flags were carried onto the endpoints the migration created, so nothing changed for existing integrations.

They cannot be set when you create a new endpoint: a new endpoint always receives the standard payload. If you still depend on either, keep using the migrated endpoint, or contact Zyphe support before pointing traffic at a new one.