Account and account group webhooks

Throughout the account lifecycle, Upvest sends webhook events to notify you of changes at each stage. Monitor these webhooks to track account group creation, account activation, status changes, and closure.

Account events

The ACCOUNT.* event type notifies you of changes to an individual account's lifecycle.

Event	Trigger	When It Fires
`ACCOUNT.CREATED`	Account is created.	Immediately when POST `/accounts` completes successfully.
`ACCOUNT.ACTIVATED`	Account becomes active.	When user onboarding is complete and all approval prerequisites are met.
`ACCOUNT.UPDATED`	Account details change.	When account properties are modified (e.g., name update).
`ACCOUNT.LOCKED`	Account is locked.	When an account is restricted from trading or other operations.
`ACCOUNT.CLOSING_INITIATED`	Account closure begins.	When account closure is initiated via API or manual process.
`ACCOUNT.CLOSED`	Account is closed.	When account closure completes and zero balance is confirmed.

Account group events

The ACCOUNT_GROUP.* event type notifies you of changes to an account group's lifecycle.

Event	Trigger	When It Fires
`ACCOUNT_GROUP.CREATED`	Account group is created.	Immediately when POST `/account_groups` completes successfully.
`ACCOUNT_GROUP.ACTIVATED`	Account group becomes active.	When user onboarding is complete and all approval prerequisites are met.
`ACCOUNT_GROUP.UPDATED`	Account group details change.	When account group properties are modified. For `PERSONAL` account groups, we only send this event when the `type` or `users` is updated.
`ACCOUNT_GROUP.LOCKED`	Account group is locked.	When an account group is restricted from operations.
`ACCOUNT_GROUP.CLOSING_INITIATED`	Account group closure begins.	When account group closure is initiated via API or manual process.
`ACCOUNT_GROUP.CLOSED`	Account group is closed.	When account group closure completes and zero balance is confirmed.

Example webhook payloads

Account lifecycle webhook examples

When account lifecycle events occur, you receive one of the following ACCOUNT.* events:

{
  "id": "56510309-d9de-4730-9b5b-4a0ed047f3a9",
  "created_at": "2021-07-21T14:10:00Z",
  "type": "ACCOUNT.CREATED",
  "object": {
    "id": "ad45b27f-c0e7-4cfb-b48c-a83670dbdfbd",
    "created_at": "2020-08-24T14:15:22Z",
    "updated_at": "2020-08-24T14:15:22Z",
    "account_group_id": "fa2414ed-8d62-46fd-85ed-565a340c81d6",
    "type": "TRADING",
    "users": [
      {
        "id": "9c36af78-91a0-4174-a515-fc81214e3dab",
        "type": "OWNER"
      }
    ],
    "account_number": 1,
    "name": "Main account",
    "status": "PENDING_APPROVAL"
  },
  "webhook_id": "b838bde5-b6df-4f1f-bfc4-71d3fb01d430"
}

Account group lifecycle webhook examples

When account group lifecycle events occur, you receive one of the following ACCOUNT_GROUP.* events:

{
  "id": "72da9e41-9926-419f-976e-4c8069a04249",
  "created_at": "2021-07-21T14:10:00Z",
  "type": "ACCOUNT_GROUP.CREATED",
  "object": {
    "id": "9d95820d-4333-46b6-98de-04ab7512e76f",
    "created_at": "2020-08-24T14:15:22Z",
    "updated_at": "2020-08-24T14:15:22Z",
    "type": "PERSONAL",
    "status": "PENDING_APPROVAL",
    "users": [
      {
        "id": "413715f2-5401-4b97-8055-034a6b879f8c",
        "type": "OWNER"
      }
    ],
    "securities_account_number": "123456789"
  },
  "webhook_id": "9df39835-be87-4243-9018-f2500b39cee6"
}

Recommended workflow

Use webhooks to track account and account group lifecycle events automatically:

Create an account group

Call POST /account_groups to create an account group for the user or business. Receive ACCOUNT_GROUP.CREATED webhook immediately.

Monitor for account group activation (webhook)

Your webhook handler receives an ACCOUNT_GROUP.ACTIVATED event when the account group is ready for use (user onboarding complete, all checks passed).

Create an account within the account group

Call POST /accounts to create an account in the active account group. Receive ACCOUNT.CREATED webhook immediately.

Monitor for account activation (webhook)

Your webhook handler receives an ACCOUNT.ACTIVATED event when the account is ready for trading (typically when associated with ACTIVE status).

Perform account operations

Once ACCOUNT.ACTIVATED is received, you can place orders, query positions, and perform other account-level operations.

Track account status changes (webhook)

Your webhook handler receives ACCOUNT.LOCKED, ACCOUNT.CLOSING_INITIATED, or ACCOUNT.CLOSED events as the account lifecycle progresses.