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 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

{
  "id": "2df83681-6a42-4837-a554-a8197335bcfa",
  "created_at": "2021-11-19T13:06:51.980159529Z",
  "type": "USER.CREATED",
  "object": {
      "created_at": "2021-11-22T09:04:42Z",
      "updated_at": "2021-11-22T09:04:42Z",
      "first_name": "Jane",
      "last_name": "Doe",
      "email": "jane.doe@example.com",
      "salutation": "SALUTATION_FEMALE",
      "title": "PROF",
      "birth_date": "1990-01-01",
      "birth_city": "Berlin",
      "birth_country": "DE",
      "birth_name": "Smith",
      "nationalities": [
        "DE",
        "CH"
    ],
      "address": {
          "address_line1": "Torstrasse",
          "address_line2": "12a",
          "city": "Berlin",
          "country": "DE",
          "postcode": "10115",
          "state": "BE"
      },
      "id": "a1752f00-93d5-4b77-a148-959cd315581b",
      "postal_address": {
          "address_line1": "Thorstrasse",
          "address_line2": "123",
          "city": "Berlin",
          "country": "DE",
          "postcode": "10115",
          "state": "BE"
      },
      "status": "ACTIVE",
      "branch_id": "e6373bfa-ff12-4004-8de9-747ac96764da",
      "tags": [
        "CLIENT_EMPLOYEE"
      ]
  },
  "webhook_id": "1b097e06-8a14-4181-b72a-de0972a3c57b"
}

User data change webhook example

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

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

{
  "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"
}

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

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

Recommended workflow

To implement user onboarding and role lifecycle tracking with webhooks:

Subscribe to user events — Listen for USER.* events to track user creation and activation.
Subscribe to check events where applicable — Listen for USER_CHECK.* events to monitor KYC and compliance verification when checks are submitted through the API.
Subscribe to role events — Listen for ROLE.* events to track role creation, activation, and deactivation.
Track user state in your system — Update your database when webhooks arrive.
Track activation — Use USER.ACTIVATED to confirm that the user has become active after the required onboarding flow completes.
Monitor data changes — Listen for USER.DATA_CHANGED and USER.DATA_CHANGE_FAILED events when users update their information.
Handle offboarding — When user offboarding initiates, prepare to close related accounts and resources.
Set up error handling — Implement retry logic for webhook delivery failures.

See implementing webhooks for setup instructions.