Instruments webhooks

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

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

Clients can subscribe to webhooks to track instrument status changes, fractional trading availability, and reference data updates in real time.

When instruments are onboarded, change status, or have their data updated, the following events are sent via webhook:

Trading status events

Instruments transition between trading states as they are onboarded, activated, or deactivated. The following events reflect these state changes:

Event Type	Description	When Triggered
`INSTRUMENT.ONBOARDED`	A new instrument has been added to the Upvest trading universe.	When Upvest adds a new instrument.
`INSTRUMENT.ACTIVATED`	An instrument's trading status has been set to `ACTIVE`.	When an instrument becomes available for trading.
`INSTRUMENT.DEACTIVATED`	An instrument's trading status has been set to `INACTIVE`.	When an instrument is suspended or delisted and can no longer be traded.

Trading status webhook example

{
  "id": "de4e9e75-5c74-44c7-b741-9b3e0d85f4de",
  "created_at": "2022-08-31T17:28:00.00Z",
  "type": "INSTRUMENT.ACTIVATED",
  "object": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "created_at": "2022-03-31T17:28:00.00Z",
    "updated_at": "2022-08-31T17:28:00.00Z",
    "isin": "DE0007664005",
    "wkn": "766400",
    "name": "Volkswagen (VW) St. Aktie.",
    "fractional_trading": true,
    "trading_status": "ACTIVE"
  },
  "webhook_id": "0af63506-289c-4051-8859-4e17ec89b002"
}

Fractional trading events

Instruments may have fractional trading enabled or disabled independently of their trading status. The following events notify you of these changes:

Event Type	Description	When Triggered
`INSTRUMENT.FRACTIONAL_TRADING_ENABLED`	Fractional trading has been enabled for an instrument.	When an instrument becomes eligible for nominal orders.
`INSTRUMENT.FRACTIONAL_TRADING_DISABLED`	Fractional trading has been disabled for an instrument.	When an instrument is no longer eligible for nominal orders.

Fractional trading webhook example

Fractional trading is now available for this instrument. The fractional_trading field in the instrument object will be true.

Data change events

Instrument reference data such as name or identifiers may be updated over time:

Event Type	Description	When Triggered
`INSTRUMENT.DATA_CHANGED`	An instrument's reference data has been updated.	When Upvest updates the instrument's name, identifiers, or other reference fields.

Data change webhook example

Reference data for the instrument has changed. Retrieve the latest instrument details with GET /instruments/{instrument_id} to update your records.

Recommended workflow

To implement instrument tracking with webhooks:

Subscribe to all instrument events — Listen for INSTRUMENT.* events to receive real-time updates.
Track instrument state in your system — Update your records when webhooks arrive instead of polling the API.
Handle trading status changes — Prevent orders for instruments with INACTIVE status when you receive INSTRUMENT.DEACTIVATED.
Handle fractional trading changes — Update your UI to reflect whether nominal orders are permitted when you receive INSTRUMENT.FRACTIONAL_TRADING_ENABLED or INSTRUMENT.FRACTIONAL_TRADING_DISABLED.
Retrieve full instrument details if needed — Call GET /instruments/{instrument_id} to fetch the latest data after an INSTRUMENT.DATA_CHANGED event.
Set up error handling — Implement retry logic for webhook delivery failures.

See Implementing webhooks for setup instructions.