How do I subscribe to an event?

Providing you are a LUSID user with sufficient privileges, you can create a subscription to a particular event, for example the LUSID ‘portfolio created’ event. See the list of events.

You can then attach email, SMS, webhook and/or AWS SQS notifications to the subscription in order to inform people and/or take action when the event occurs.

Note: For creating and updating tasks in the Workflow Service when LUSID emits a system event, see system event handlers instead.

Using the Notification REST API

Currently, you can create one subscription per API call.

Obtain an API access token.

Call the CreateSubscription API for your LUSID domain, passing in your API access token and:

A scope and code that together uniquely identify the subscription.
An eventType that is the id of the event you want to subscribe to. See how to find this out.
Optionally, a filter to subscribe to the event conditionally.
Optionally, a service user ID for useAsAuth. If omitted, the subscription is created on behalf of the user sending the request. This means if the Personal user account is deleted, any subscriptions created on the user's behalf will be affected. We recommend users instead create subscriptions on behalf of service users with useAsAuth; read more on it here.

The following example subscribes to the PortfolioCreated event conditionally; that is, when a portfolio is created in the Finbourne-Examples scope:

curl -X POST "https://<your-domain>.lusid.com/notification/api/subscriptions" 
  -H "Authorization: Bearer <your-API-access-token>" 
  -H "Content-Type: application/json" 
  -d '{
  "id": {
    "scope": "PortfolioEvents",
    "code": "PortfolioCreatedEvent"
  },
  "displayName": "PortfolioCreatedInExampleScope",
  "description": "Subscribe to the event fired when a portfolio is created in the Finbourne-Examples scope",
  "status": "Active",
  "matchingPattern": {
    "eventType": "PortfolioCreated",
    "filter": "Body.portfolioScope eq 'Finbourne-Examples'"
  },
  "useAsAuth": "00uji4ve5haBc1Hlf2p7"  
}'

The response is as follows:

{
  "id": {
    "scope": "PortfolioEvents",
    "code": "PortfolioCreatedEvent"
  },
  "displayName": "PortfolioCreatedInExampleScope",
  "description": "Subscribe to the event fired when a portfolio is created in the Finbourne-Examples scope",
  "status": "Active",
  "matchingPattern": {
    "eventType": "PortfolioCreated",
    "filter": "Body.portfolioScope eq 'Finbourne-Examples'"
  },
  "createdAt": "2022-07-08T10:13:36.8915431+00:00",
  "userIdCreated": "00u91lo2d7X42sdse2p7",
  "modifiedAt": "2022-07-08T10:13:36.8915431+00:00",
  "userIdModified": "00u91lo2d7X42sdse2p7",
  "useAsAuth": "00uji4ve5haBc1Hlf2p7",
  "href": "https://<your-domain>.lusid.com/notification/api/subscriptions/PortfolioEvents/PortfolioCreatedEvent"
}

Once subscribed, you should attach at least one email, SMS, webhook or AWS SQS notification to the subscription in order to actually notify someone or perform an operation.

Using the LUSID web app