# User webhooks

Webhooks are a mechanism for your software to automatically receive information about user lifecycle events, roles, and onboarding progress. By leveraging webhooks, you remove the need to poll the API for updates.

For general information about webhooks, refer to the [Implementing webhooks](/products/tol/getting_started/implementing_webhooks) guide.

Clients can subscribe to webhooks to track user onboarding, KYC verification, roles, data changes, and offboarding events across their entire user base.

When users are created, verified, modified, or offboarded, the following events are sent via webhook:

## User events

Users transition through states as they are onboarded and managed. The following events reflect these state changes:

| **Event Type** | **Description** | **When Triggered** |
|  --- | --- | --- |
| `USER.CREATED` | A user has been created. | Immediately after user creation via API. |
| `USER.ACTIVATED` | **DEPRECATED** A user's own onboarding is complete. What the user can do is determined by the roles assigned to them — subscribe to `ROLE.*` events for capability decisions. See [Role-based activation](/products/tol/guides/users/role_based_activation). | After all onboarding steps required by the user's operating model are complete. |
| `USER.DEACTIVATED` | **DEPRECATED**  A user has been deactivated (account suspended or disabled). | When user is deactivated manually or by system. |
| `USER.DATA_CHANGED` | A user's data has been successfully changed (e.g., name, address). | When a data change request completes. |
| `USER.DATA_CHANGE_FAILED` | A user's data change request has been rejected. | When a data change request fails validation. |
| `USER.OFFBOARDING_INITIATED` | A user's offboarding process has started. | When offboarding request is submitted. |
| `USER.OFFBOARDED` | A user has been fully offboarded and account is closed. | When offboarding process completes. |


### User webhook example

USER.CREATED
USER.ACTIVATED
The user's own onboarding is complete — all onboarding requirements (KYC verification, checks) have passed. To determine what the user can do on a given account group or business, listen for the `ROLE.ACTIVATED` event of their role. See [Role-based activation](/products/tol/guides/users/role_based_activation).

USER.DEACTIVATED
The user has been deactivated and cannot access the platform until reactivated.

USER.OFFBOARDING_INITIATED
User offboarding has been initiated. Outstanding obligations (such as account closure) are being processed.

USER.OFFBOARDED
User offboarding is complete and the user account is closed.

### User data change webhook example

USER.DATA_CHANGED
User data change request succeeded. The user object reflects the updated information (e.g., name, address, nationality changed).

USER.DATA_CHANGE_FAILED
User data change request failed. Check the failure reason in the webhook object for validation details.

## Role events

If your operating model uses role-based onboarding flows, such as business representatives or child account guardians, roles transition through states as they are created and activated for account groups and businesses. The following events reflect those state changes:

| **Event Type** | **Description** | **When Triggered** |
|  --- | --- | --- |
| `ROLE.CREATED` | A role has been created and is pending activation. | Immediately after role creation. |
| `ROLE.ACTIVATED` | A role has been activated and is now in effect. | When all role requirements are fulfilled and the role becomes active. |
| `ROLE.DEACTIVATED` | A role has been deactivated. | When the role is disabled or no longer applies. |


### Role webhook example

ROLE.CREATED
```json
{
  "id": "2df83681-6a42-4837-a554-a8197335bcfa",
  "created_at": "2021-11-22T09:04:42Z",
  "type": "ROLE.CREATED",
  "object": {
    "id": "baf05386-0459-4e8c-9ac9-cd6442f194dd",
    "created_at": "2025-04-01T10:11:40Z",
    "updated_at": "2025-04-01T10:11:40Z",
    "user_id": "9c36af78-91a0-4174-a515-fc81214e3dab",
    "entity_type": "ACCOUNT_GROUP",
    "entity_id": "413715f2-5401-4b97-8055-034a6b879f8c",
    "role_type": "GUARDIAN",
    "custody_type": "JOINT_CUSTODY",
    "status": "PENDING"
  },
  "webhook_id": "1b097e06-8a14-4181-b72a-de0972a3c57b"
}
```

ROLE.ACTIVATED
```json
{
  "id": "2df83681-6a42-4837-a554-a8197335bcfa",
  "created_at": "2021-11-22T09:04:42Z",
  "type": "ROLE.ACTIVATED",
  "object": {
    "id": "e8b5a51d-8baf-4d0b-8a3b-8f8f8f8f8f8f",
    "created_at": "2025-04-01T10:11:40Z",
    "updated_at": "2025-04-01T10:11:40Z",
    "user_id": "0d10c51f-33f2-4399-b8ab-92ec84e6b2f0",
    "entity_type": "BUSINESS",
    "entity_id": "6deb17c8-950e-4377-b500-5522af5ef712",
    "role_type": "LEGAL_REPRESENTATIVE",
    "status": "ACTIVE"
  },
  "webhook_id": "1b097e06-8a14-4181-b72a-de0972a3c57b"
}
```

ROLE.DEACTIVATED
Role deactivation means the role is no longer effective. For example, a guardian role can be deactivated when the underlying eligibility conditions no longer apply.

## User check events

User checks (KYC verification, compliance checks) transition through states as they are processed. Each check generates events:

| **Event Type** | **Description** | **When Triggered** |
|  --- | --- | --- |
| `USER_CHECK.CREATED` | A user check (KYC, compliance, etc.) has been created and is pending processing. | Immediately after check submission. |
| `USER_CHECK.PASSED` | A user check has passed and the user meets the requirement. | When check verification completes successfully. |
| `USER_CHECK.FAILED` | A user check has failed and requirements are not met. | When check fails verification. |


### User check webhook example

USER_CHECK.CREATED
Check has been created and is pending. The `status` field in the check object will be `CREATED`.

USER_CHECK.PASSED
The following example shows a TOL webhook payload for a passed user check.

```json
{
  "id": "38fc59d0-fc42-46ef-9512-824773219b2e",
  "created_at": "2021-11-19T13:06:57.820371265Z",
  "type": "USER_CHECK.PASSED",
  "object": {
      "check_confirmed_at": "2021-08-02T15:04:05Z",
      "data_download_link": "https://storage.cloud.google.com/upvest-mock-documents/Test_KYC_documents.zip",
      "document_expiration_date": "2028-01-02",
      "document_type": "PASSPORT",
      "id": "32cbb9a2-dd3b-4e60-a5af-9b41460049dc",
      "user_id": "7b39529a-e68c-4688-8242-7549d10d6084",
      "method": "VIDEO_ID",
      "nationality": "RU",
      "provider": "IDNOW",
      "status": "PASSED",
      "type": "KYC"
  },
  "webhook_id": "1b097e06-8a14-4181-b72a-de0972a3c57b"
}
```

USER_CHECK.FAILED
Check verification failed. The `status` field in the check object will be `FAILED`. Reasons for failure are provided in the check object details.

## Recommended workflow

To implement user onboarding and role lifecycle tracking with webhooks:

1. **Subscribe to user events** — Listen for `USER.*` events to track user creation and activation.
2. **Subscribe to check events where applicable** — Listen for `USER_CHECK.*` events to monitor KYC and compliance verification when checks are submitted through the API.
3. **Subscribe to role events** — Listen for `ROLE.*` events to track role creation, activation, and deactivation.
4. **Track user state in your system** — Update your database when webhooks arrive.
5. **Track activation** — Use `ROLE.ACTIVATED` to determine what the user can do on a given account group or business. For more information, refer to [Role-based activation](/products/tol/guides/users/role_based_activation).
6. **Monitor data changes** — Listen for `USER.DATA_CHANGED` and `USER.DATA_CHANGE_FAILED` events when users update their information.
7. **Handle offboarding** — When user offboarding initiates, prepare to close related accounts and resources.
8. **Set up error handling** — Implement retry logic for webhook delivery failures.


See [implementing webhooks](/products/tol/getting_started/implementing_webhooks) for setup instructions.