# Rebalancing API Webhooks

Webhooks are a mechanism for your software to automatically receive information about rebalancing execution events. By leveraging webhooks, you remove the need to poll the API for rebalancing state changes.

For general information about webhooks, refer to the [Implementing webhooks](/products/byol/getting_started/implementing_webhooks) guide.

Clients can subscribe to webhooks to track rebalancing execution orders as they are placed, executed, and settled by the market.

When rebalancing is triggered, orders are generated and executed. Each execution order generates webhook events reflecting its lifecycle:

## Rebalancing execution order events

When a portfolio rebalancing is triggered, the system generates individual execution orders for each security adjustment. These orders transition through states as they are processed:

| **Event Type** | **Description** | **When Triggered** |
|  --- | --- | --- |
| `REBALANCING_EXECUTION_ORDER.NEW` | A rebalancing order has been created and submitted to the market. | When rebalancing starts and orders are generated. |
| `REBALANCING_EXECUTION_ORDER.PROCESSING` | The rebalancing order is being processed by the market. | After initial acceptance at the venue. |
| `REBALANCING_EXECUTION_ORDER.FILLED` | The rebalancing order has been fully executed. | When all quantities match at the venue. |
| `REBALANCING_EXECUTION_ORDER.CANCELLED` | The rebalancing order has been cancelled. | When cancellation is confirmed. |


### Rebalancing execution order webhook example

REBALANCING_EXECUTION_ORDER.NEW
```json
{
  "id": "54b8d84f-5bd0-4e43-bf0f-164388cb4c23",
  "created_at": "2021-07-21T14:10:00.00Z",
  "type": "REBALANCING_EXECUTION_ORDER.NEW",
  "object": {
    "id": "eb5ba93f-5dfe-4bf1-8571-4da0caacc80c",
    "execution_id": "760abce7-e6b5-440b-bdf3-88e35ed6417a",
    "created_at": "2021-07-21T14:10:00.000Z",
    "updated_at": "2021-07-21T14:10:00.000Z",
    "account_id": "debf2026-f2da-4ff0-bb84-92e45babb1e3",
    "portfolio_order_id": "4f2f5db9-ef4e-4dbf-80a1-bffc71985d6c",
    "status": "PROCESSING"
  },
  "webhook_id": "cd2e4183-4e62-4e0f-981b-44b594d14610"
}
```

REBALANCING_EXECUTION_ORDER.PROCESSING
Order is being processed by the market. The `status` field in the object will be `PROCESSING`.

REBALANCING_EXECUTION_ORDER.FILLED
Order execution is complete. The `status` field in the object will be `FILLED`.

REBALANCING_EXECUTION_ORDER.CANCELLED
Order has been cancelled. The `status` field in the object will be `CANCELLED`.

## Related execution events

In addition to rebalancing execution order events, you will also receive standard **order execution events** for each rebalancing trade. These are the same execution events as regular orders:

| **Event Type** | **Description** |
|  --- | --- |
| `EXECUTION.FILLED` | A rebalancing trade fill has occurred (see [Orders webhooks](/products/byol/guides/orders/orders_webhooks)). |
| `EXECUTION.SETTLED` | A rebalancing trade settlement is confirmed (typically T+2). |


Monitor both `REBALANCING_EXECUTION_ORDER.*` and `EXECUTION.*` events to fully track rebalancing progress.

## Recommended workflow

To implement rebalancing tracking with webhooks:

1. **Trigger rebalancing** — Call `POST /portfolios/rebalancings/executions` to start
2. **Subscribe to rebalancing events** — Listen for `REBALANCING_EXECUTION_ORDER.*` events
3. **Track execution orders** — Update your system when each order's state changes
4. **Monitor underlying fills** — Also listen for `EXECUTION.FILLED` and `EXECUTION.SETTLED` events
5. **Determine completion** — Rebalancing is complete when all execution orders are either `FILLED` or `CANCELLED`


See [implementing webhooks](/products/byol/getting_started/implementing_webhooks) for setup instructions.