# Partner Webhooks

This document outlines our webhook specification. Each partner integrating with our platform should be ready to receive messages which correspond to these asynchronous event notifications.

Our API expects that there is a separate endpoint for each object type as defined in this specification. Partners should be prepared to handle notifications for objects that are either initiated on partner or our side:

* objects like customers or customer products are created by partners and partners receive the id when the create operation is submitted
* objects like documents creating during identification verification process are created based on the business rules implemented on our side and partners receive notification with id that is new to a partner. In such case partner should call the get operation to receive the object data.

## Important Webhook Behavior Notes

### Order Status Webhooks

Partners receive webhook notifications for order lifecycle events. Each notification includes a `notificationType` field (`CREATED`, `UPDATED`, or `VALIDATION_ERROR`) and a `status` field reflecting the current order state.

**Positive status notifications:**

* **PLACED**: The order has been accepted and placed on the exchange.
* **FILLED**: The order has been fully executed.
* **PARTIALLY\_FILLED**: Part of the order has been executed (remaining quantity is still active).
* **SETTLED**: The order has been fully settled — funds or assets have been transferred.
* **CANCELED**: Sent only when an order cancellation is **successful**. If a cancellation request fails, **no webhook is sent** and the order retains its previous status.

**Negative status notifications:**

* **INVALID**: Sent when an order fails API-level validation (e.g., the `Requestor-ID` references a non-active natural person). The `notificationType` will be `VALIDATION_ERROR`.
* **REJECTED**: Sent when an order is rejected by the exchange, including the rejection reason in the payload.
* **EXPIRED**: Sent when an order expires before being fully filled (e.g., a limit order that was not matched within the validity period).

### Unused Statuses

The following statuses may appear in API schemas but are **not currently used** by the system and should not be expected in webhook notifications:

* `CANCELLATION_REJECTED`
* `CANCELLATION_ACCEPTED`
* `RECONCILIATION_CORRECTION`

## Communication Diagram

Example communication diagram

```mermaid
sequenceDiagram
    box Partner
        participant PW as Webhook server
        participant P as API Client
    end
    participant T as Our API
    autonumber

    opt
        P->>+T: Create or update object
        T-->>-P: OK (including object id)
    end

    T->>+T:Asynchronous operations
    T->>PW:Notification 1 - EVENT_TYPE 1
    T->>PW:Notification 2 - EVENT_TYPE 2 
    T->>-PW:Notification n - EVENT_TYPE n

    opt
        P->>+T: Get object
        T-->>-P: OK (object data)
    end
   
   
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.tradevest.ai/documentation/partner-webhooks.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.