# Account liquidation webhook events

This guide documents the webhook event types available for the account liquidations domain. Webhooks enable you to track liquidation progress through its complete lifecycle and be notified immediately at each state transition, eliminating the need to poll for status updates.

## Event types overview

Upvest sends webhook notifications whenever an account liquidation's status changes during processing. The **ACCOUNT_LIQUIDATION.*** events fire at each state transition as the liquidation progresses from initial request through completion or cancellation, allowing your application to track the entire lifecycle.

Account liquidations involve selling all positions in an account through individual orders. Each liquidation progresses through defined states, with webhooks sent for each transition: NEW (request received) → PROCESSING (orders being executed) → FILLED (all orders executed) → SETTLED (settled) or CANCELLED.

## Account liquidation event table

| Event type | Trigger | Status | Description |
|  --- | --- | --- | --- |
| **ACCOUNT_LIQUIDATION.NEW** | Liquidation requested. | Immediate | A liquidation request has been placed and relevant checks are being conducted. |
| **ACCOUNT_LIQUIDATION.PROCESSING** | First order execution begins. | Immediate | All individual sell orders have been created, order checks have passed, and execution has started. |
| **ACCOUNT_LIQUIDATION.FILLED** | All orders executed. | Immediate | All individual orders have been executed successfully. Securities and cash positions have been updated. |
| **ACCOUNT_LIQUIDATION.SETTLED** | Orders settled. | Within hours. | The liquidation settlement is complete. Final cash balances are confirmed. |
| **ACCOUNT_LIQUIDATION.CANCELLED** | Cancellation or error. | Immediate | The liquidation has been cancelled by the client or due to an error at the trading partner. |


## Account liquidation lifecycle

Account liquidations follow a standard lifecycle with state transitions. The following diagram shows the typical liquidation flow:

```
Liquidation requested
     ↓
ACCOUNT_LIQUIDATION.NEW
     ↓
Individual orders created
     ↓
ACCOUNT_LIQUIDATION.PROCESSING
     ↓
Individual orders execute (ORDER.* and EXECUTION.* events)
     ↓
All orders executed
     ↓
ACCOUNT_LIQUIDATION.FILLED
     ↓
Orders settle
     ↓
ACCOUNT_LIQUIDATION.SETTLED
     ↓
Liquidation complete

(Alternative: ACCOUNT_LIQUIDATION.CANCELLED at any point)
```

Each individual order in the liquidation also generates standard order and execution events (for example, `ORDER.NEW`, `ORDER.PROCESSING`, `ORDER.FILLED`, and `EXECUTION.SETTLED`). These are linked to the parent liquidation via the `account_liquidation_id` in the order's `client_reference` field.

## Account liquidation event details

### ACCOUNT_LIQUIDATION.NEW

Sent when a liquidation request has been received and preliminary checks are in progress.

```json
{
  "id": "56510309-d9de-4730-9b5b-4a0ed047f3a9",
  "created_at": "2021-07-21T14:10:00.00Z",
  "type": "ACCOUNT_LIQUIDATION.NEW",
  "object": {
    "id": "b2f541dc-a27b-4d5a-b970-41812b0892b9",
    "created_at": "2021-07-21T14:10:00.000Z",
    "updated_at": "2021-07-21T14:10:00.000Z",
    "account_id": "debf2026-f2da-4ff0-bb84-92e45babb1e3",
    "user_id": "81dfb00e-9be6-4617-8994-dfd0407f34df",
    "cash_amount": "",
    "currency": "EUR",
    "status": "NEW",
    "orders": []
  },
  "webhook_id": "b838bde5-b6df-4f1f-bfc4-71d3fb01d430"
}
```

### ACCOUNT_LIQUIDATION.PROCESSING

Sent when the first individual sell order begins execution. The `orders` array will contain at least one order.

### ACCOUNT_LIQUIDATION.FILLED

Sent when all individual orders have been executed successfully. The `cash_amount` field is now populated with the proceeds.

### ACCOUNT_LIQUIDATION.SETTLED

Sent when all individual orders have been settled and final balances are confirmed.

### ACCOUNT_LIQUIDATION.CANCELLED

Sent when the liquidation has been cancelled — either at client request or due to an error at the trading partner.

## Field descriptions

| Field | Type | Description |
|  --- | --- | --- |
| `id` | string (UUID). | Unique identifier for this webhook event. |
| `created_at` | string (ISO 8601 timestamp). | When the webhook event was created (UTC). |
| `type` | string | Event type: `ACCOUNT_LIQUIDATION.NEW`, `ACCOUNT_LIQUIDATION.PROCESSING`, `ACCOUNT_LIQUIDATION.FILLED`, `ACCOUNT_LIQUIDATION.SETTLED`, or `ACCOUNT_LIQUIDATION.CANCELLED`. |
| `object.id` | string (UUID). | Account liquidation ID — use this to retrieve the liquidation status via `GET /accounts/{account_id}/liquidations/{liquidation_id}`. |
| `object.created_at` | string (ISO 8601 timestamp). | When the liquidation was created (UTC). |
| `object.updated_at` | string (ISO 8601 timestamp). | When the liquidation was last updated (UTC). |
| `object.account_id` | string (UUID). | Account ID being liquidated. |
| `object.user_id` | string (UUID). | User ID associated with the account. |
| `object.cash_amount` | string (decimal). | Cash proceeds from sold positions (populated after FILLED state). |
| `object.currency` | string | Currency of the account (e.g., `EUR`, `GBP`). |
| `object.status` | string | Current liquidation status: `NEW`, `PROCESSING`, `FILLED`, `SETTLED`, or `CANCELLED`. |
| `object.orders` | array | Array of individual sell orders created for the liquidation. Each order has `id`, `side` (always `SELL`), and `state` fields. |
| `webhook_id` | string (UUID). | Unique identifier for this webhook subscription — used for debugging. |


## Recommended workflow

Follow these steps to implement account liquidation tracking via webhooks:

1. **Set up webhook handler**
Create an HTTP endpoint to listen for incoming webhooks. Endpoint must validate webhook signatures and respond with HTTP `200`, `202`, or `204` within 30 seconds.
For more information, refer to [Implementing webhooks](/products/byol/getting_started/implementing_webhooks)
2. **Subscribe to ACCOUNT_LIQUIDATION events**
Call `POST /webhooks` with `type: ["ACCOUNT_LIQUIDATION"]`. This delivers all event types: `ACCOUNT_LIQUIDATION.NEW`, `ACCOUNT_LIQUIDATION.PROCESSING`, `ACCOUNT_LIQUIDATION.FILLED`, `ACCOUNT_LIQUIDATION.SETTLED`, `ACCOUNT_LIQUIDATION.CANCELLED`.
For more information, refer to [Webhook subscription](/api/webhook-subscriptions/create_webhook)
3. **Initiate liquidation**
Call `POST /accounts/{account_id}/liquidations` with the user or business ID to begin the liquidation process.
For more information, refer to [Initiate liquidation](/api/liquidations/create_account_liquidation)
4. **Handle ACCOUNT_LIQUIDATION.* webhooks**
Your webhook handler receives events at each state transition. Track the liquidation progress in your application state.
5. **Track individual orders (optional)**
Each individual order in the liquidation also generates ORDER.* events. The liquidation ID is available in each order's `client_reference` field for mapping.
For more information, refer to [Order webhook events](/products/byol/guides/orders/orders_webhooks)