Webhook Integration

Webhooks notify your backend when verification results or lifecycle events change. Zyphe sends an HTTPS POST to each webhook endpoint your organization has configured for that event; your endpoint verifies the request, records or queues the event, and acknowledges it.

Webhooks are configured on the organization

Destinations are no longer a single URL on a flow. An organization owns a registry of endpoints, each with its own event subscriptions, flow scope, signing secret, and payload version — and one event can reach several of them. Existing per-flow URLs were converted automatically and keep behaving exactly as before.

Start at Webhook Endpoints.

Integration checklist

1. Create an endpoint. Add your public HTTPS URL under Webhooks in the Zyphe Dashboard, or through the endpoints API.
2. Subscribe to the events you handle. Endpoints receive only what they ask for. See the event catalog.
3. Choose the signing secret. The shared organization secret, or one dedicated to this endpoint. Store it server-side; never expose it in browser or mobile code.
4. Read the raw request body. Signature verification must use the exact bytes received, before JSON parsing or re-serialization.
5. Verify X-Signature. Reject requests with an invalid signature or an unacceptable timestamp. See Webhook Signature.
6. Dispatch the event. On V2 branch on the envelope's type; on LEGACY_V1 use data for results and eventData for notifications. See Receiving Webhooks.
7. Acknowledge delivery. Return 2xx promptly — 200 if the endpoint is LEGACY_V1 — then do slower work asynchronously.
8. Make processing idempotent. Failed deliveries are retried, so receiving the same logical event more than once must be safe.

Test before going live

Configure endpoints in sandbox first: the sandbox and production registries are separate. Use the webhook trigger and monitor tools in the flow's developer controls to inspect the payload, delivery attempts, response status, and errors before sending production traffic.

Choose the right reference

You need to…	Read…
Configure destinations, filters, secrets, and limits	Webhook Endpoints
Understand LEGACY_V1 vs V2, and migrate between them	Payload Versions
Implement the HTTP endpoint and route events	Receiving Webhooks
Inspect fields for DV, PoA, Form, Phone, Wallet, SPID/CIE, KYB, AML, or Geolocation	Webhook Payload
Look up event, status, and reason enums	Statuses and codes
Handle failed or review-required results	Failure and Review Events
Verify that a request came from Zyphe	Webhook Signature
Reconcile events with records in your system	Custom Fields
Attach a callback to one verification run	Session Webhooks
Retrieve document images or full result details	Export API
Migrate from the legacy data.kyc format	Backwards Compatibility

The pages above each own one part of the contract. Payload examples are kept in the payload reference rather than repeated throughout the integration guide.