Views:

In this tutorial we'll see how to use the Notifications API to create a LUSID webhook notification.

Let's imagine we want to automatically seed all new portfolios we create with some cash. To do this, we need to subscribe to the portfolio created event that LUSID emits every time a transaction portfolio is created and attach a webhook notification to post to the LUSID UpsertTransactions API. 

Note: To complete this tutorial, you must have suitable access control permissions. This can most easily be achieved by assigning your LUSID user the built-in lusid-administrator role, which  should already be the case if you are the domain owner. If you are informed you do not have a license to perform a certain operation, contact support.

Step 1: Authorising webhook notifications

Before we can create any webhooks, we need to authorise LUSID to 'run as you'; that is, to trigger webhooks with your level of access control permissions. See how to complete the one-time authorisation process.

Note: This is a one-time operation. Once you have performed it for the first webhook you create, you don't need to perform it for subsequent webhooks. 

Step 2: Subscribing to the portfolio created event

We need to subscribe to the portfolio created event using the CreateSubscription API before we can create a notification, passing in:

  • An API access token as a Bearer token in the Authorization HTTP header. See how to obtain a token.
  • PortfolioEvent as our scope and AnyPortfolioCreated as our code for the subscription.
  • A displayName and description for the subscription.
  • The eventType to subscribe to. In our case, we want to subscribe to the PortfolioCreated event type every time it occurs, so we leave the filter parameter empty.
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": "PortfolioEvent",
    "code": "AnyPortfolioCreated"
  },
  "displayName": "Any Portfolio Created",
  "description": "Subscribes to all PortfolioCreated events",
  "status": "Active",
  "matchingPattern": {
    "eventType": "PortfolioCreated",
    "filter": ""
  }
}'

The response is as follows:

{
  "id": {
    "scope": "PortfolioEvent",
    "code": "AnyPortfolioCreated"
  },
  "displayName": "Any Portfolio Created",
  "description": "Subscribes to all PortfolioCreated events",
  "status": "Active",
  "matchingPattern": {
    "eventType": "TransactionPortfolioCreated",
    "filter": ""
  },
  "createdAt": "2023-02-15T10:13:36.8915431+00:00",
  "userIdCreated": "00uji4twb7X42sdse2p7",
  "modifiedAt": "2023-02-15T10:13:36.8915431+00:00",
  "userIdModified": "00uji4twb7X42sdse2p7"
  "useAsAuth":"00uji4twb7X42sdse2p7"
  "href": "https://<your-domain>.lusid.com/notification/api/subscriptions/PortfolioEvent/AnyPortfolioCreated"
}

You can sign in to the LUSID web app to view the new subscription on the Subscription Management dashboard, available from the top left menu under Jobs & Scheduling:

Step 3: Attaching a webhook notification to the subscription

Now that we have subscribed to the portfolio created event, we can create a webhook notification for the subscription to post to the UpsertTransactions API each time the event occurs. In this tutorial, we want to seed all newly-created portfolios with 10,000,000 USD and 7,500,000 GBP cash. To do so, we call the CreateNotification API, passing in our API access token and:

  • The scope and code of the subscription to attach the notification to. In our case, PortfolioEvent and AnyPortfolioCreated.
  • A displayName and unique notificationId to refer to the notification once created.
  • A notificationType containing:
    • A Type of Webhook.
    • The HttpMethod for the type of request we want to make to the LUSID REST API. In our case, we want to make a POST request.
    • The Url we want to make a POST request to.
    • A ContentType of Json.
    • A Content object which contains the expected payload for the UpsertTransactions API. 
curl -X POST "https://<your-domain>.lusid.com/notification/api/subscriptions/PortfolioEvent/AnyPortfolioCreated/notifications" 
  -H "Authorization: Bearer <your-API-access-token>" 
  -H "Content-Type: application/json" 
  -d '{
  "notificationId": "PortfolioCreatedWebhook",
  "displayName": "Seed Portfolio With Cash", 
  "description": "Any portfolio created seed with cash",
  "notificationType": {
    "Type":  "Webhook",
    "HttpMethod": "Post",
    "Url": "/api/api/transactionportfolios/{{Body.portfolioScope}}/{{Body.portfolioCode}}/transactions",
    "AuthenticationType": "Lusid",
    "ContentType": "Json",
    "Content": [
      { 
        "transactionId": "SeedFundsTransactionUSD",
        "type": "FundsIn",
        "instrumentIdentifiers": {"Instrument/default/Currency": "USD"},
        "transactionDate": "{{Header.timestamp}}",
        "settlementDate": "{{Header.timestamp}}",
        "units": 10000000,
        "transactionPrice": {
          "price": 1,
          "type": "Price"
        },
        "totalConsideration": {
          "amount": 10000000,
          "currency": "USD"
        },
        "transactionCurrency": "USD",
      },
      { 
        "transactionId": "SeedFundsTransactionGBP",
        "type": "FundsIn",
        "instrumentIdentifiers": {"Instrument/default/Currency": "GBP"},
        "transactionDate": "{{Header.timestamp}}",
        "settlementDate": "{{Header.timestamp}}",
        "units": 7500000,
        "transactionPrice": {
          "price": 1,
          "type": "Price"
        },
        "totalConsideration": {
          "amount": 7500000,
          "currency": "GBP"
        },
        "transactionCurrency": "GBP",
      }
     ]
}'

Step 4: Checking that a new portfolio is automatically seeded with cash

Now that we have created a webhook notification, we can create a new transaction portfolio to check that new portfolios are now automatically seeded with cash. Let's create a new portfolio via the Portfolios dashboard in the LUSID web app with scope FBNUniversity and code NewTradingPortfolio​​​​​:

Once the new portfolio has been created, navigate from the top left menu in the web app to Dashboard > Transactions and select the new portfolio. We can see that the webhook notification has successfully seeded our new portfolio with the USD and GBP cash amounts specified earlier:

Keywords: notification service, webhook, event