Webhook Integration

Webhooks notify your backend when verification results or lifecycle events change. Zyphe sends an HTTPS POST request to the webhook URL configured for the flow; your endpoint verifies the request, records or queues the event, and returns 200 OK.

Integration checklist

1. Configure the endpoint. Add your public HTTPS webhook URL in the flow settings in the Zyphe Dashboard.
2. Keep the secret safe. Store your organization's webhook secret on your server. Never expose it in browser or mobile code.
3. Read the raw request body. Signature verification must use the exact bytes received, before JSON parsing or re-serialization.
4. Verify X-Signature. Reject requests with an invalid signature or an unacceptable timestamp. See Webhook Signature.
5. Dispatch the event. Standard result webhooks use data; notification webhooks use eventData. See Receiving Webhooks.
6. Acknowledge delivery. Return 200 OK promptly, then perform slower application work asynchronously.
7. Make processing idempotent. Delivery failures are retried, so receiving the same logical event more than once must be safe.

:::tip Test before going live 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…
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 status, event, 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
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.