# API Endpoints and Webhooks

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

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

Clients can subscribe to webhooks, regardless of the API integration for incoming or outgoing securities transfers.

To reflect the related status changes, the following [securities transfer events](/api/securities-transfers/securities_transfer_event) are sent out.

| **Status** | **Description** |
|  --- | --- |
| `SECURITIES_TRANSFER.NEW` | A securities transfer has been requested. |
| `SECURITIES_TRANSFER.PROCESSING` | Processing of the transfer has started and instructions sent into the market. |
| `SECURITIES_TRANSFER.SETTLED` | The transfer was executed at the custodian level. |
| `SECURITIES_TRANSFER.CANCELLED` | The transfer has been either canceled by Upvest or possibly rejected by the custodian bank. |
| `SECURITIES_TRANSFER.DATA_CHANGE` | The transfer’s data was changed but the status remained the same.  During the transfer process, Upvest may need to update certain fields, like `settlement_date` or `place_of_settlement` to ensure correct market processing.  If data changes are not important for you, you can ignore the `SECURITIES_TRANSFER.DATA_CHANGE` events. |


## Incoming transfer webhook

New
{
  "id": "b5d0d9d0-bb8e-48b4-b2af-11df2b522353",
  "created_at": "2024-01-22T14:10:00.00Z",
  "type": "SECURITIES_TRANSFER.NEW",
  "object": {
    "id": "9637e68f-7065-4131-a072-6d57044ebd8c",
    "created_at": "2024-01-22T14:10:00.00Z",
    "updated_at": "2024-01-22T14:12:34.56Z",
    "direction": "INCOMING",
    "status": "NEW",
    "transfer_type": "NO_OWNER_CHANGE",
    "instrument_id": "US0378331005",
    "instrument_id_type": "ISIN",
    "quantity": "10",
    "user_id": "7e9a0529-d289-4f4a-ae01-c2cd013d582e",
    "account_id": "d396b7c3-aa67-488a-8e39-4a1a7cbeb9f4",
    "settlement_reference": "b82dc5985558fdr2",
    "counterparty": {
      "bic": "DUMBZZ33XXX",
      "account_number": "1234567891",
      "name": "Max Mustermann"
    },
    "place_of_settlement": "DAKVDEFFXXX",
    "trade_date": "2024-01-22",
    "settlement_date": "2024-01-23"
  },
  "webhook_id": "cab4673a-1381-4404-aec4-982dae33a38c"
}
Settled
{
  "id": "b5d0d9d0-bb8e-48b4-b2af-11df2b522353",
  "created_at": "2024-01-22T14:10:00.00Z",
  "type": "SECURITIES_TRANSFER.SETTLED",
  "object": {
    "id": "9637e68f-7065-4131-a072-6d57044ebd8c",
    "created_at": "2024-01-22T14:10:00.00Z",
    "updated_at": "2024-01-22T14:12:34.56Z",
    "direction": "INCOMING",
    "status": "SETTLED",
    "transfer_type": "NO_OWNER_CHANGE",
    "instrument_id": "US0378331005",
    "instrument_id_type": "ISIN",
    "quantity": "10",
    "user_id": "7e9a0529-d289-4f4a-ae01-c2cd013d582e",
    "account_id": "d396b7c3-aa67-488a-8e39-4a1a7cbeb9f4",
    "settlement_reference": "b82dc5985558fdr2",
    "counterparty": {
      "bic": "DUMBZZ33XXX",
      "account_number": "1234567891",
      "name": "Max Mustermann"
    },
    "place_of_settlement": "DAKVDEFFXXX",
    "trade_date": "2024-01-22",
    "settlement_date": "2024-01-23",
    "actual_settlement_date": "2024-01-24"
  },
  "webhook_id": "cab4673a-1381-4404-aec4-982dae33a38c"
}

## Outgoing transfer webhook

New
{
  "id": "b5d0d9d0-bb8e-48b4-b2af-11df2b522353",
  "created_at": "2024-01-22T14:10:00.00Z",
  "type": "SECURITIES_TRANSFER.NEW",
  "object": {
    "id": "9637e68f-7065-4131-a072-6d57044ebd8c",
    "created_at": "2024-01-22T14:10:00.00Z",
    "updated_at": "2024-01-22T14:12:34.56Z",
    "direction": "OUTGOING",
    "status": "NEW",
    "transfer_type": "NO_OWNER_CHANGE",
    "instrument_id": "US0378331005",
    "instrument_id_type": "ISIN",
    "quantity": "10",
    "user_id": "7e9a0529-d289-4f4a-ae01-c2cd013d582e",
    "account_id": "d396b7c3-aa67-488a-8e39-4a1a7cbeb9f4",
    "settlement_reference": "b82dc5985558fdr2",
    "counterparty": {
      "bic": "DUMBZZ33XXX",
      "account_number": "1234567891",
      "name": "Max Mustermann"
    },
    "place_of_settlement": "CEDELULLXXX",
    "trade_date": "2024-01-22",
    "settlement_date": "2024-01-23"
  },
  "webhook_id": "cab4673a-1381-4404-aec4-982dae33a38c"
}

Settled
{
  "id": "b5d0d9d0-bb8e-48b4-b2af-11df2b522353",
  "created_at": "2024-01-22T14:10:00.00Z",
  "type": "SECURITIES_TRANSFER.SETTLED",
  "object": {
    "id": "9637e68f-7065-4131-a072-6d57044ebd8c",
    "created_at": "2024-01-22T14:10:00.00Z",
    "updated_at": "2024-01-22T14:12:34.56Z",
    "direction": "OUTGOING",
    "status": "SETTLED",
    "transfer_type": "NO_OWNER_CHANGE",
    "instrument_id": "US0378331005",
    "instrument_id_type": "ISIN",
    "quantity": "10",
    "user_id": "7e9a0529-d289-4f4a-ae01-c2cd013d582e",
    "account_id": "d396b7c3-aa67-488a-8e39-4a1a7cbeb9f4",
    "settlement_reference": "b82dc5985558fdr2",
    "counterparty": {
      "bic": "DUMBZZ33XXX",
      "account_number": "1234567891",
      "name": "Max Mustermann"
    },
    "place_of_settlement": "CEDELULLXXX",
    "trade_date": "2024-01-22",
    "settlement_date": "2024-01-23",
    "actual_settlement_date": "2024-01-24"
  },
  "webhook_id": "cab4673a-1381-4404-aec4-982dae33a38c"
}