# 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](/products/omnibus/getting_started/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

INSTRUMENT.ACTIVATED
```json
{
  "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"
}
```

INSTRUMENT.ONBOARDED
A new instrument is available in the Upvest trading universe. The `trading_status` field will be `ACTIVE`.

INSTRUMENT.DEACTIVATED
An instrument is no longer available for trading. The `trading_status` field will be `INACTIVE`. Orders placed for this instrument will be rejected until it is reactivated.

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

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

INSTRUMENT.FRACTIONAL_TRADING_DISABLED
Fractional trading is no longer available for this instrument. The `fractional_trading` field in the instrument object will be `false`. Nominal orders for this instrument will be rejected.

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

INSTRUMENT.DATA_CHANGED
Reference data for the instrument has changed. Retrieve the latest instrument details with **GET** [`/instruments/{instrument_id}`](/api/instruments/retrieve_instrument) to update your records.

## Recommended workflow

To implement instrument tracking with webhooks:

1. **Subscribe to all instrument events** — Listen for `INSTRUMENT.*` events to receive real-time updates.
2. **Track instrument state in your system** — Update your records when webhooks arrive instead of polling the API.
3. **Handle trading status changes** — Prevent orders for instruments with `INACTIVE` status when you receive `INSTRUMENT.DEACTIVATED`.
4. **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`.
5. **Retrieve full instrument details if needed** — Call `GET /instruments/{instrument_id}` to fetch the latest data after an `INSTRUMENT.DATA_CHANGED` event.
6. **Set up error handling** — Implement retry logic for webhook delivery failures.


See [Implementing webhooks](/products/omnibus/getting_started/implementing_webhooks) for setup instructions.