Customer webhooks - Yara

Customer webhook events are in preview as part of USD Virtual Accounts.

Customer webhooks notify your server when Yara creates a customer or applies a verification state. Configure and filter webhook endpoints from the Webhooks page in the dashboard.

Events

Event	Fires when
`customer.created`	The customer is ready for verification.
`customer.verification.submitted`	Yara accepts a verification submission and stores its current normalized state.
`customer.verification.approved`	A verification submission becomes `VERIFIED`.
`customer.verification.information_requested`	A verification submission needs more information and becomes `REQUIRES_REVIEW`.
`customer.verification.rejected`	A verification submission becomes `REJECTED`.

Every accepted verification request creates customer.verification.submitted. If processing returns a terminal or information-requested state immediately, Yara also creates the corresponding state event. When a pending submission reaches a terminal state later, Yara sends the terminal event after it applies that state.

Payload

{
  "id": "2b342f2e-0995-47c7-b5e1-3f918302cc47",
  "event": "customer.verification.approved",
  "data": {
    "api_version": "v1",
    "customer_id": "908a76cf-4ff1-4e0e-bda4-d3a939970abc",
    "verification_submission_id": "a9203946-43ef-45ed-a806-7b0bbd3de424",
    "tier": "TIER_2",
    "customer_type": "INDIVIDUAL",
    "status": "VERIFIED",
    "occurred_at": "2026-08-03T12:05:00Z"
  },
  "created_at": "2026-08-03T12:05:00Z"
}

Customer events contain stable Yara IDs and normalized state. They do not contain names, email addresses, BVNs, government identification numbers, documents, image data, or internal provider identifiers. A rejected event may include the safe rejection_reasons also available from the authorized verification read endpoint.

Handle deliveries safely

Verify the X-Yara-Signature against the raw request body before parsing the payload.
Return a 2xx quickly and process the event asynchronously.
De-duplicate deliveries using the top-level event id.
Fetch the customer or submission if you need the latest state after receiving an event.

See the general webhook guide for endpoint setup, signature verification, delivery history, and retry behavior.