The event notification service group is dedicated to the support of an enterprise wide event notification mechanism. It currently implements one resource, /ens/v1/activities/ through which a client application can subscribe to information about important events.
The events provided through this system are primarily intended to provide near-realtime updates to a client application or a client enterprise system. This is different from the /trade/messages endpoint which is primarily intended to provide ready formatted feedback to the end user.
Using the Event Notification Service
Starting a subscription
To use the notification service, you setup a subscription to the /ens/v1/activities/subscriptions endpoint. You may specify the following parameters.
Selecting Activities
When setting up the subscription the caller must specify which type of activities or events they want to receive information about. Currently four types of events are supported, the contents of each is described further below.
Selecting FieldGroups
For subscriptions to Orders and Positions, you may specify two field groups, which will be returned in addition to the main message structure.
.
Selecting the scope of the subscription
It is possible to select the scope of the subscription.This is particularly important if the user setting up the subscription is a user of client in the top of a client hierarchy.
Consider the following setup:
In this situation:
| A user under | With | Will receive events for |
|---|---|---|
| 8328393 (top house) | IncludeSubAccounts, ClientKey and AccountKey undefined | All events for all clients and accounts under this top level client, so:
|
| 8328393 (top house) | IncludeSubAccounts=false | All events for client 8328393 and that clients accounts: (BlockTrade8393, Demo_8328393 and ERROR_8939) |
| 8328393 (top house) | ClientKey=<clientKey for 8328395> | All events for client 8328395 and all his/her account(s). |
| 8328395 | IncludeSubAccounts,ClientKey and AccountKey undefined | All events under 8328395 and all his/her accounts. |
In addition you can use the combination of ClientKey and AccountKey to only only receive events pertaining to a specific single account.
Selecting the starting point of receiving events
If the subscription is started without setting neither a SequenceId, nor a FromDateTime, the first event received, will be the first event occurring after the start of the subscription.
You may request to receive events "back in time", by specifying a FromDateTime or a known existing SequenceId. In this situation you will still not get any data in the "snapshot". Instead you will start receiving these previous messages over the streaming channel. The maximum rate for receiving old messages is capped at 50 msgs/second.
Events in the past
The cache of available past events is a maximum of 3 calendar days in the streaming based subscription and 14 calendar days in the GET ens/v1/activities endpoint.
The purpose is only to allow an application to recover from a situation, where the streaming subscription has been broken, not to provide access to a long term record of all historical events.
Receiving Data
Following a successful subscription, data will start flowing via the streaming channel only. Contrary to most other OpenAPI endpoints, this service does not provide initial data via a snapshot. All events, both past events (if a SequenceId or FromDate has been set) and all current events are delivered via the streaming channel.
Message Formats
Shared Message Properties
All messages have a few shared properties:
Specific Events
Depending of the activity type, additional fields will be available. For detailed information about each event type please refer to:
- Order Events
- Position Events
- Margin Call Events
- Account Funding Events
- Account Depreciation Events
- Position Depreciation Events
- Corporate Action Events
- Security Transfer Events
See also the live sample on ENS (with source) and the live sample on ENS for Corporate Actions (with source)