Skip to main content

Event Reports (Webhooks)

Getting Started​

Webhooks are a way to receive information about events occurring asynchronously in the Trader Backend systems.

They are HTTP requests sent to an endpoint on the integrators' server with a JSON payload. It is required that the endpoint supports HTTPS with TLSv1.2 or higher. To get up and running with webhooks, create an endpoint that implements the following:

  1. Receive a POST event notification.
  2. Respond with a 2xx HTTP status within 10 seconds.
    • 200 - OK
    • 204 - No Content
    • 201 - Created
  3. Support HTTPS TLSv1.2 or higher on the web server.
  4. Use the idempotency value (eventId field) to ignore repeated events.

When the endpoint is available on a public web server, the webhooks can be activated by contacting Trader Backend support with the URL and which events to listen for.

Events​

The webhooks are sent as JSON events using HTTP POST where the payload is specific for each event type.

The event type is sent in every webhook request, so it is possible to have a single endpoint to receive all webhook events, but it may also be configured to send each event type to different endpoints.

Webhook configuration is per tenant and also client and the implications of this depend on how the tenant and/or client is set up.

Examples​

{
  "eventId": "74de0dd8-6cde-41e8-93e2-e9bf11c6e11f",
  "type": "TradeExecutionReport",
  "timestamp": "2023-31-10T09:18:41.5355253Z",
  "dataUrl": "https://{{endpoint}}",
  "additionalData": [
    {
      "key": "clientId",
      "value": "a5f13c94-bee8-484e-9ed8-e366ca0db201"
    },
    {
      "key": "clientOrderId",
      "value": "0a340c79-9866-49de-a4f6-2e0b9181b627"
    }
  ]
}
{
  "eventId": "0c944b2b-8b2c-494c-98c8-5922db4fe594",
  "type": "ClientKistamQueryResultReceived",
  "timestamp": "2023-31-10T09:18:41.5355253Z",
  "dataUrl": "https://{{endpoint}}",
  "additionalData": [
    {
      "key": "clientId",
      "value": "acf64434-1575-449c-bd56-548acea83097"
    }
  ]
}

HTTP Headers​

The following definition shows the HTTP headers that will always be sent in the webhook request. Note that there may be additional headers sent on the future requirements.

Header NameDescription
X-Rea-Trader-Backend-Content-Signature-HMACContains the signature.
Content-TypeWill always be application/json

Examples​

POST http://{{endpoint}}
X-Rea-Trader-Backend-Content-Signature-HMAC: aG1hZz1zaMdaXUR1xmU=
Content-Type: application/json

Event Acknowledge​

Trader Backend will try to deliver the webhook event for 48 hours with an exponential backoff in case of delivery failure.

HTTP requests will be acknowledged as processed for any HTTP 2xx status code response given above response codes. The endpoint has to respond within 10 seconds, otherwise, it is acknowledged as failed.

Other than HTTP 2xx codes given above, all the response codes will be accepted as a fail. Trader Backend will retry sending the event if it is acknowledged as a fail. The initial retry is done after 5 minutes, and every retry will double the time between retry. This process will eliminate after 48 hours. After that, it will stay as failed.

A webhook endpoint that keeps failing will be disabled.

Endpoint Authentication​

Trader Backend supports two types of authentication, and it is recommended to use one of these authentication mechanisms, besides checking the HMAC signature.

Configuration of these are configured by contacting Trader Backend support.

  • NoAuth = 0 (If host to host VPN exists)
  • ApiKey,
  • DataCryptogram, (HMAC-SHA256 with shared secret)
  • MTLS (not supported right now, contact Trader Backend support for detail)

Static HTTP Headers​

It is possible to add static HTTP headers to the webhook HTTP request. This can be used for but is not limited to static HTTP header authentication like HTTP Basic.

Authorization: Basic dXNlxt8hbYV6cGDz23drcmQ=

Mutual TLS​

Mutual TLS (mTLS) applies two-way encryption at the transport layer. To enable mTLS for a webhook endpoint, the client certificate has to be sent to Trader Backend support team. The certificate has to be supplied in PEM format with the entire intermediate certificate chain. Certificate expiry is not monitored by Trader Backend, so it is up to the integrator to supply Trader Backend with a new certificate before expiry

Best Practices​

Parsing​

Any breaking change of the event payload will be versioned, for example removing a property or changing the format of a property value. However, properties may be added without version incrementation and therefore the event payload should not be parsed using a strict JSON parser.

Idempotence​

The webhooks may be sent multiple times under some circumstances, therefore the receiving endpoint should be idempotent. To simplify implementation of this, each request includes a unique id in the JSON payload (eventId) that stays the same for successive requests of the same event. This value can be used to register if an event has been received before.

Retries​

The webhook has a different retry count for each event report type. Some events can be retried multiple times before proceeding to other events.

Unsubscription​

Cancelling your subscription to webhook events means that you won't receive any information pertaining to a specific event type. This action effectively blocks the transmission of data related to the specified event category, ensuring that your system remains free from any updates or notifications associated with that particular event type.

Webhook unsubscriptions can be set on tenant and client level with below endpoints.

Tenant Unsubscription Client Unsubscription

List of possible events​

TradeExecutionReport​

Event DescriptionWhen FiredParameters/PayloadWhat to Do
When placing an order through Trader OMS API, the API will give a success or fail response.

This response does not mean that the order is filled or failed in the market. It represents whether “placing order“ is successful or not.

The order filling, decline, reject, delete by market, etc. are notified later from the market to API. In this case, API will report these via the event.		After order is placed successfully, the market can decide/perform one of the following: fills the order, cancels the order, declines the order, deletes the orderclientId

clientOrderId		Retrieve the order from the Trader OMS API in order to get the last status of the order

TradeOrderCancelReject​

Event DescriptionWhen FiredParameters/PayloadWhat to Do
When canceling an order through Trader OMS API, the API will give a success or fail response.

This response does not mean that the order is canceled in the market. It represents whether “request for canceling order“ is successful or not.

The order canceling is done by the market. When canceling is REJECTED later, by market, in this case, the API will report this via the event.		If you requested to cancel an order, however when cancelling is rejected by the market.clientId

clientOrderId		Retrieve the order from the Trader OMS API in order to get the last status of the order

TradeOrderModifyReject​

Event DescriptionWhen FiredParameters/PayloadWhat to Do
When a modify order request through OMS API, it will give a success or fail response.

This response does not mean that the order is modified in the market. It represents whether “request for modify order“ is successful or not.

The order modify request is done by the market. When modify request is REJECTED later, by market, in this case this event will be generated.		If you requested to modify an order, however when modify request is rejected by the market.clientId

clientOrderId		Retrieve the order from the Trader OMS API in order to get the last status of the order

TradeCaptureReport​

Event DescriptionWhen FiredParameters/PayloadWhat to Do
After placing an order, the order may be in NEW, PENDING_NEW state if placing the order was successful. In some rare cases, order filling, decline, reject, delete by market, etc. can be notified later to the OMS API from the target market. If you did not receive any execution report for a longer time, then you can request an order report for it over the OMS api. Once we receive the result of this from corresponding market, then this event will be fired.When we receive a capture report from target market and order state has been updated as a result of this.clientId

clientOrderId		Retrieve the order from the Trader OMS API in order to get the last status of the order

PaymentSDDInstructionUploaded​

Event DescriptionWhen FiredParameters/PayloadWhat to Do
After setting up a SEPA Direct Debit Mandate, you can create instructions for money transfers using the TraderBackend MoneyManagement API. This allows you to transfer money from a BankAccount (ReferenceAccount) to an InternalAccount (Cash Account) on a specified date. The transfer isn't immediate and will be confirmed via a notification event.After SEPA Direct Debit Instruction is created, the transfer instruction is uploaded within SEPA system. When this upload is completed this event will be fired.bankAccountId

sepaDirectDebitMandateId

sepaDirectDebitInstructionId		Retrieve the SEPA Direct Debit Instruction from the Trader Backend MoneyManagement API in order to get the last status of the SDD Instruction.

PaymentSDDInstructionReceived​

Event DescriptionWhen FiredParameters/PayloadWhat to Do
Money received from a BankAccount (ReferenceAccount) into the InternalAccount (Cash Account) of the client.When money is received into InternalAccount (Cash Account) of the client.bankAccountId

sepaDirectDebitMandateId

sepaDirectDebitInstructionId		Retrieve the SEPA Direct Debit Instruction from the Trader Backend MoneyManagement API in order to get the last status of the SDD Instruction.

You can inform your client user about this.

PaymentSDDInstructionReverted​

Event DescriptionWhen FiredParameters/PayloadWhat to Do
Money returned back to client BankAccount (ReferenceAccount) as per client’s request to their house bank, which can happen according to SEPA regulation within a time frame.When SEPA Direct Debit Instruction is failed and it has been notified to side.bankAccountId

sepaDirectDebitMandateId

sepaDirectDebitInstructionId		Retrieve the SEPA Direct Debit Instruction from the Trader Backend MoneyManagement API in order to get the last status of the SDD Instruction.

You can inform your client user about this.

PaymentSDDInstructionFailed​

Event DescriptionWhen FiredParameters/PayloadWhat to Do
A SEPA Direct Debit Instruction has been uploaded to the bank has been failed due to some technical or business logic related reason.When banking provider updates us about the failure during reconciliation of individual SEPA Direct Debit Instructions.bankAccountId

sepaDirectDebitMandateId

sepaDirectDebitInstructionId		Retrieve the SEPA Direct Debit Instruction from the Trader Backend MoneyManagement API in order to get the last status of the SDD Instruction.

You can inform your client user about this.

ClientKistamQueryResultReceived​

Event DescriptionWhen FiredParameters/PayloadWhat to Do
This event is created when we receive a Kistam query result from the authorities, that can be result of first onboarding of the client or after manual Kistam query triggering or as a result of yearly Kistam data updateKistam result received from regulatory authoritiesclientIdRetrieve client data along with the tax identifiers and update caller side if necessary.

NewInternalAccountTransaction​

Event DescriptionWhen FiredParameters/PayloadWhat to Do
This event is used to provide real-time alerts for significant financial activities occurring in Internal Accounts (Cash Accounts).Occurs when external bank accounts related money movements occur on cash accounts.internalAccountId

internalAccountTransactionId		Upon receiving this event, the client system is expected to retrieve the relevant internal account transaction. This access allows client to analyze various attributes of the transaction associated with incoming or outgoing external money movements.

NewInternalAccountStatement​

Event DescriptionWhen FiredParameters/PayloadWhat to Do
This event is created when a new internal account statement is generated on a particular account.When a new internal account statement is generated on a particular account.internalAccountId

year

fileNumber		Retrieve the new internal account statement from Trader Backend Api and process it according to the appropriate workflows in your own system.

NewDepositAccountStatement​

Event DescriptionWhen FiredParameters/PayloadWhat to Do
This event is created when a new deposit account statement is generated on a particular account.When a new deposit account statement is generated on a particular account.depositAccountId

year

fileNumber		Retrieve the new deposit account statement from Trader Backend Api and process it according to the appropriate workflows in your own system.

BONewClientCreate​

Event DescriptionWhen FiredParameters/PayloadWhat to Do
This event is created when a new client is created from Trader back office web application.When a new client is successfully created.clientIdRetrieve the new client information and process it according to the appropriate workflows in your own system.

BONewDepositAccountCreate​

Event DescriptionWhen FiredParameters/PayloadWhat to Do
This event is created when a new deposit account is created from Trader back office web application.When a new deposit account is successfully created.depositAccountIdRetrieve the new deposit account details and process it according to the appropriate workflows in your own system.

BONewInternalAccountCreate​

Event DescriptionWhen FiredParameters/PayloadWhat to Do
This event is created when a new internal account is created from Trader back office web application.When a new internal account is successfully created.internalAccountIdRetrieve the new internal account details and process it according to the appropriate workflows in your own system.

BONewBankAccountCreate​

Event DescriptionWhen FiredParameters/PayloadWhat to Do
This event is created when a new bank account is created from Trader back office web application.When a new bank account is successfully created.bankAccountIdRetrieve the new bank account details and process it according to the appropriate workflows in your own system.

BOClientStateUpdate​

Event DescriptionWhen FiredParameters/PayloadWhat to Do
This event is created when existed client status is updated from Trader back office web application.When the client status updated to a new state.clientIdRetrieve the client details and process it according to the appropriate workflows in your own system.

BODepositAccountStateUpdate​

Event DescriptionWhen FiredParameters/PayloadWhat to Do
This event is created when existed deposit account status is updated from Trader back office web application.When the deposit account status updated to a new state.depositAccountIdRetrieve the deposit account details and process it according to the appropriate workflows in your own system.

BOInternalAccountStateUpdate​

Event DescriptionWhen FiredParameters/PayloadWhat to Do
This event is created when existed internal account status is updated from Trader back office web application.When the internal account status updated to a new state.internalAccountIdRetrieve the internal account details and process it according to the appropriate workflows in your own system.

BOBankAccountStateUpdate​

Event DescriptionWhen FiredParameters/PayloadWhat to Do
This event is created when existed bank account status is updated from Trader back office web application.When the bank account status updated to a new state.bankAccountIdRetrieve the bank account details and process it according to the appropriate workflows in your own system.

KycCreate​

Event DescriptionWhen FiredParameters/PayloadWhat to Do
This event is created when a new kyc session is created from Trader back office web application.When a new kyc session is successfully created.clientId

initiatorKycId		Retrieve the new kyc session details and process it according to the appropriate workflows in your own system.

KycUpdate​

Event DescriptionWhen FiredParameters/PayloadWhat to Do
This event is created when existed kyc session details is updated from Trader back office web application.When the kyc session status updated to a new state.clientId

initiatorKycId		Retrieve the kyc session details and process it according to the appropriate workflows in your own system.

ClientUpdate​

Event DescriptionWhen FiredParameters/PayloadWhat to Do
This event is created when existing client information is updated from Trader back office web application.When the client information updated.clientId
Retrieve the client details and process it according to the appropriate workflows in your own system.

WithdrawalUpdate​

Event DescriptionWhen FiredParameters/PayloadWhat to Do
This event is created when existing withdrawal request's status has been changed.When the internal account withdrawal request updated.internalAccountId

initiatorWithdrawalRequestId		Retrieve the withdrawal request details and process it according to the appropriate workflows in your own system.

BankAccountAMLClosure​

Event DescriptionWhen FiredParameters/PayloadWhat to Do
This event is created when existing bank account is closed due to the AML regulations.When the bank account is closed due to the AML regulations.bankAccountIdRetrieve the bank account details and process it according to the appropriate workflows in your own system.

PaymentSCTInstructionUpdated​

Event DescriptionWhen FiredParameters/PayloadWhat to Do
This event is created when existing payment instruction's status has been changed.When the payment instruction updated.initiatorPaymentIdRetrieve the payment instruction details and process it according to the appropriate workflows in your own system.

TradeExecutionStatement​

Event DescriptionWhen FiredParameters/PayloadWhat to Do
This event is created when new trade execution statement created.When the trade execution statement created.clientId

clientOrderId

executionId		Retrieve the trade execution statement from OMS Api and process it according to the appropriate workflows in your own system.

LossThresholdReport​

Event DescriptionWhen FiredParameters/PayloadWhat to Do
This event is created when new loss threshold report created.When the loss threshold report created.clientId

snapshotDate		Retrieve the loss threshold details and process it according to the appropriate workflows in your own system.

CorporateActionStatement​

Event DescriptionWhen FiredParameters/PayloadWhat to Do
This event is created when new corporate action statement created.When the corporate action statement created.corporateActionIdRetrieve the corporate action statement details and process it according to the appropriate workflows in your own system.

NewDepositAccountTransaction​

Event DescriptionWhen FiredParameters/PayloadWhat to Do
This event is used to provide real-time alerts for significant financial activities occurring in Deposit Accounts (Security Accounts)When deposit account register security movement.depositAccountId

depositAccountTransactionId		Upon receiving this event, the client system is expected to retrieve the relevant deposit account transaction. This access allows client to analyze various attributes of the transaction associated with incoming or outgoing external money movements.

CorporateActionMetadata​

Event DescriptionWhen FiredParameters/PayloadWhat to Do
This event is created when new corporate action metadata received.When the corporate action metadata received and saved.corporateActionIdRetrieve the corporate action metadata and process it according to the appropriate workflows in your own system.

CorporateActionWithChoiceNotif​

Event DescriptionWhen FiredParameters/PayloadWhat to Do
This event is created when new corporate action with choice or meeting announcement received.When the corporate action with choice or meeting announcement received and saved.corporateActionIdRetrieve the corporate action with choice or meeting data and notify your customers with an appropriate email format.