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.

Registering your endpoints

You register one endpoint per event type. Registering an event type that already has an endpoint replaces it - there is exactly one webhook per event.

POST /webhooks

{
  "eventType": "CUSTOMER_NOTIFICATION",
  "url": "https://your-address.example.com/e9c1a702ccab",
  "headers": [
    { "name": "api-key", "value": "<your-api-key>" }
  ]
}

The headers you supply are sent back on every call to that endpoint, which is how you authenticate the delivery as coming from us.

GET /webhooks-missing is the quickest way to check you have not left an event type unhandled.

Event catalogue

Every event type, the endpoint you need to expose for it, and the payload you will receive.

For the exact payload of each schema, see the Partner Webhooks API reference.

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 Order Statuses

The following order 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

Transfer Status Webhooks

TransferNotification carries three independent enums - notificationType, status and validationError - but only a few of their combinations are ever delivered. The table below is the complete set.

Combinations that never occur, even though the schema allows them:

• notificationType = CREATED for a partner-initiated transfer. A successful POST /transfers produces UPDATED, not CREATED - do not wait for a CREATED notification.
• notificationType = DELETED - transfers are never deleted.
• status = RECEIVED - an internal marker for a transfer that is not yet stored; it is never delivered.
• status = RECONCILED - part of the schema but not currently used by the system.
• status = PENDING on an incoming transfer - deposits are booked in a single step.

The payload does not tell you the direction

TransferNotification has no direction or transaction-type field. transferId alone does not say whether the event describes a deposit or a withdrawal, and the same status values are used for both.

To build a "deposit received" flow, resolve the direction after the notification arrives:

• call GET /transfers/{transferId} and read transactionType (INCOMING_TRANSFER or OUTGOING_TRANSFER), or
• match on what you initiated - every outgoing transfer starts with your own POST /transfers, so a TRANSFER_NOTIFICATION for a transferId you have never seen is always an incoming transfer.

INVALID and REJECTED each cover two different situations

The partner-facing statuses are a collapsed view of a larger internal set, so status alone is not enough to decide what to do.

INVALID means one of two things, and notificationType separates them:

1. notificationType = VALIDATION_ERROR (with validationError) - the request failed validation and nothing was stored. GET /transfers/{transferId} may return 404, and the row backing it is not guaranteed to persist, so take everything you need from the notification payload itself.
2. notificationType = UPDATED (no validationError) - the transfer was accepted, stored, and then failed at the payment provider. The transfer exists and stays readable.

REJECTED also means one of two things, and the payload does not distinguish them:

1. the payment provider refused the transfer, or
2. the transfer was executed and the funds were later returned.

Both arrive as notificationType = UPDATED with status = REJECTED. Read rejectReason from GET /transfers/{transferId} if you need the reason.

PENDING is collapsed the same way: internally an outgoing transfer moves through several provider states (queued, awaiting approval, compliance review) that all surface as PENDING. A hop between two of them sends no webhook, so you will not receive repeated identical PENDING notifications.

Recovering missed notifications

A notification we could not deliver is not lost. Undelivered notifications are retained for 30 days, after which they may be removed.

GET /undelivered-webhooks?eventType=CUSTOMER_NOTIFICATION&limit=20

The endpoint accepts eventType, startDate, endDate, limit and cursor, so you can replay a specific window after an outage.

Once you have processed them, acknowledge with:

POST /undelivered-webhooks

This marks the notification with the given id and every earlier one as delivered, so they stop appearing in the list. Acknowledge only after you have durably stored the events - the operation is not reversible.

Communication Diagram

Example communication diagram

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