Positions webhooks

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

For general information about webhooks, refer to the Implementing webhooks guide.

Clients can subscribe to webhooks to track position changes and account valuations in real time.

When positions change or valuations are calculated, the following events are sent via webhook:

Position events

Positions change when orders are filled, settled, or cancelled, and when corporate actions are processed. The following event reflects these changes:

Event Type	Description	When Triggered
`POSITION.UPDATED`	A position has changed.	Whenever the quantity, locked amount, or settlement status of a position changes.

Position webhook example

{
  "id": "8962b496-8d42-4560-bfab-10490dd1a724",
  "created_at": "2021-07-21T14:10:00.00Z",
  "type": "POSITION.UPDATED",
  "object": {
    "account_id": "c5161455-4d27-4781-bc74-f05532e49a77",
    "instrument": {
      "isin": "US0378331005",
      "uuid": "ccb86937-8a39-4160-8d33-85bf9e902321"
    },
    "quantity": "10.4",
    "locked_for_trading": "5",
    "pending_settlement": "2.2",
    "available_for_trading": "5.4",
    "available_for_instruction": "5.4",
    "settled_quantity": "8.2"
  },
  "webhook_id": "9df39835-be87-4243-9018-f2500b39cee6"
}

Valuation events

Upvest calculates account valuations at the end of each trading day and, for clients with a real-time pricing contract, also intraday. The following events notify you when valuations are available:

Event Type	Description	When Triggered
`ACCOUNT_VALUATION.CREATED`	An end of day account valuation has been calculated.	Every trading day after market close.
`INTRADAY_ACCOUNT_VALUATION.CREATED`	An intraday account valuation has been calculated.	Each time the security position updates.

Valuation webhook example

{
  "id": "8962b496-8d42-4560-bfab-10490dd1a721",
  "created_at": "2023-01-10T00:15:32Z",
  "type": "ACCOUNT_VALUATION.CREATED",
  "object": {
    "id": "404b170a-9042-11ed-9a51-2eabd0c03f8a",
    "created_at": "2023-01-10T00:15:22Z",
    "updated_at": "2023-01-10T00:15:22Z",
    "valuation_time": "2023-01-10T00:15:22Z",
    "account_id": "51cdc0cc-9042-11ed-b017-2eabd0c03f8a",
    "price_quality": "EOD",
    "total_security_value": {
      "amount": "142.29",
      "currency": "EUR"
    },
    "security_positions": [
      {
        "instrument": {
          "uuid": "123e4567-e89b-12d3-a456-426614174000",
          "isin": "DE0007664005"
        },
        "value": {
          "amount": "104.81",
          "currency": "EUR",
          "price_time": "2023-01-09T09:20:00Z"
        },
        "quantity": "0.65",
        "weight": "0.736595"
      },
      {
        "instrument": {
          "uuid": "48b798b7-3a62-4f30-8307-ee94d35b21b7",
          "isin": "FR0010524777"
        },
        "value": {
          "amount": "37.48",
          "currency": "EUR",
          "price_time": "2023-01-09T09:20:00Z"
        },
        "quantity": "1.00",
        "weight": "0.263405"
      }
    ]
  },
  "webhook_id": "9df39835-be87-4243-9018-f2500b39cee6"
}

Position performance and acquisition costs events

Clients can subscribe to ACCOUNT_POSITION_PERFORMANCE.* webhooks to track acquisition-cost changes in real time.

An ACCOUNT_POSITION_PERFORMANCE.UPDATED event is sent whenever:

The acquisition cost data of a position changes: This includes whenever the quantity, total cost, or pending cost quantity changes for any instrument (ISIN) within the account.

Event type	Description	When triggered
`ACCOUNT_POSITION_PERFORMANCE.UPDATED`	The acquisition costs have changed.	Whenever the quantity, total cost, or pending cost quantity for position changes.

Position performance webhook example

{
  "id": "b28a499c-755d-4e28-badf-bd8d361035ab",
  "created_at": "2026-07-02T13:10:00.00Z",
  "type": "ACCOUNT_POSITION_PERFORMANCE.UPDATED",
  "object": {
    "account_id": "f1410edd-c2c8-457b-82e6-ef833700041d",
    "account_group_id": "73b20f1a-8cdd-4b9e-8fdb-eefc719b4ebb",
    "instrument": {
      "uuid": "40d850c5-d9b5-4da8-b5f8-520ad3a0b614",
      "isin": "DE0007664005"
    },
    "acquisition_cost": {
      "calculated_at": "2026-07-02T13:10:00.00Z",
      "total_quantity": "11",
      "total_cost": {
        "amount": "375.50",
        "currency": "EUR",
        "quantity": "5"
      },
      "pending_cost_quantity": "6"
    }
  },
  "webhook_id": "36567d73-c326-4f4d-8e50-77fac38b4156"
}

Recommended workflow

To implement position tracking with webhooks:

Subscribe to position events — Listen for POSITION.* events to receive updates whenever positions change.
Subscribe to valuation events — Listen for ACCOUNT_VALUATION.* events to receive end of day account valuations.
Subscribe to position performance events — Listen for ACCOUNT_POSITION_PERFORMANCE.* events to receive acquisition costs and position changes.
Track position state in your system — Update your records when webhooks arrive instead of polling the API.
Retrieve full position details if needed — Call GET /accounts/{account_id}/positions to fetch additional context if required.
Set up error handling — Implement retry logic for webhook delivery failures.

See Implementing webhooks for setup instructions.