Ctrlk
tradevest.ai

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

Last updated