# 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 user status changes.

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` | A user has been activated and is ready to use the platform. | After all onboarding steps complete (KYC/checks pass). |
| `USER.DEACTIVATED` | 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
User activation complete. The `status` field in the user object will be `ACTIVE`. All onboarding requirements (KYC verification, checks) have passed.

USER.DEACTIVATED
User has been deactivated. The `status` field in the user object will be `INACTIVE`. The user 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. The user account is closed and the user object will reflect `status` as `OFFBOARDED`.

### 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 `USER.ACTIVATED` to confirm that the user has become active after the required onboarding flow completes.
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.