# 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.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:

ACCOUNT.CREATED
```json
{
  "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.ACTIVATED
```json
{
  "id": "72f51e2a-6a9f-429c-8d2c-5b8f1c9d4e7a",
  "created_at": "2021-07-22T10:30:00Z",
  "type": "ACCOUNT.ACTIVATED",
  "object": {
    "id": "ad45b27f-c0e7-4cfb-b48c-a83670dbdfbd",
    "created_at": "2020-08-24T14:15:22Z",
    "updated_at": "2021-07-22T10:30:00Z",
    "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": "ACTIVE"
  },
  "webhook_id": "c949cef6-c7e9-5f2f-cdfd-82e4fc02e541"
}
```

ACCOUNT.UPDATED
Account details were updated. The `status` field in the account object reflects the current account state.

ACCOUNT.LOCKED
Account has been locked. The `status` field in the account object will be `LOCKED`.

ACCOUNT.CLOSING_INITIATED
Account closure has started. The `status` field in the account object will be `CLOSING`.

ACCOUNT.CLOSED
Account has been closed. The `status` field in the account object will be `CLOSED`.

### Account group lifecycle webhook examples

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

ACCOUNT_GROUP.CREATED
```json
{
  "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"
}
```

ACCOUNT_GROUP.ACTIVATED
```json
{
  "id": "92eb0f52-aa37-52ag-086f-5d9g2d0e5350",
  "created_at": "2021-07-22T10:30:00Z",
  "type": "ACCOUNT_GROUP.ACTIVATED",
  "object": {
    "id": "9d95820d-4333-46b6-98de-04ab7512e76f",
    "created_at": "2020-08-24T14:15:22Z",
    "updated_at": "2021-07-22T10:30:00Z",
    "type": "PERSONAL",
    "status": "ACTIVE",
    "users": [
      {
        "id": "413715f2-5401-4b97-8055-034a6b879f8c",
        "type": "OWNER"
      }
    ],
    "securities_account_number": "123456789"
  },
  "webhook_id": "0e940946-bf98-5b3b-d4ee-93f5bd13f652"
}
```

ACCOUNT_GROUP.LOCKED
Account group has been locked. The `status` field in the account group object will be `LOCKED`.

ACCOUNT_GROUP.CLOSING_INITIATED
Account group closure has started. The `status` field in the account group object will be `CLOSING`.

ACCOUNT_GROUP.CLOSED
Account group has been closed. The `status` field in the account group object will be `CLOSED`.

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