> ## Documentation Index
> Fetch the complete documentation index at: https://developers.yara.cash/llms.txt
> Use this file to discover all available pages before exploring further.

# Customer webhooks

> Receive customer creation and verification state notifications.

<Note>
  Customer webhook events are in preview as part of USD Virtual Accounts.
</Note>

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

```json theme={null}
{
  "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](/wallets/guides/webhooks) for endpoint setup, signature verification,
delivery history, and retry behavior.