Views:

Related resources:

Explanation

Tutorials

Reference

Providing you are a LUSID user with sufficient access control permissions, you can create a webhook notification to call a LUSID (or ecosystem application) API when an event you have subscribed to occurs. For example, your webhook could call the LUSID UpsertTransactions API to upsert transactions when the ‘portfolio created’ event occurs. See an example.

Note the following:

  • You must have already subscribed to the event you want to attach the webhook notification to.
  • You can only call LUSID API endpoints that use PUT, POST or DELETE verbs.
  • You do not have access to API responses, so calls to API endpoints that get or list data in LUSID are ineffective.
  • We guarantee notifications are delivered once but in your implementation you should guard against them being delivered more than once.
  • Note that alternatively your webhook can call a third party (non-LUSID) API.

The following methods are available to create a webhook notification:

Using the Notification REST API

Currently, you can create one notification per API call.

  1. The first time you ever create a webhook, follow the instructions in this article to authorise LUSID to 'run as you'. 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.
  2. Obtain an API access token for the operations below.
  3. Call the CreateNotification API for your LUSID domain, passing in your API access token and:
    • The scope and code of the subscription to attach it to.
    • A displayName and unique notificationId.
    • A Type of Webhook.
    • A HttpMethod of either PUT, POST or DELETE.
    • A Url that constitutes a LUSID or ecosystem REST API without the domain prefix. To find out what the path is, examine the appropriate Swagger definition for the ecosystem application. For example:
      - /api/api/upsertinstruments to call the LUSID UpsertInstruments API. Note the double /api/api/ is intentional in the core LUSID API.
      - /drive/api/files to call the Drive CreateFile API.
    • An AuthenticationType of Lusid.
    • A ContentType of Json.
    • A Content object that contains the expected payload for the API.
    Consider the following example, of a webhook notification attached to a subscription with scope PortfolioEvents and code PortfolioCreated. Note the use of event attributes in mustache templates (highlighted in red) as placeholders for values generated by the event each time it occurs: 
    curl -X POST "https://<your-domain>.lusid.com/notification/api/subscriptions/PortfolioEvents/PortfolioCreatedEvent/notifications" 
    -H "Authorization: Bearer <your-API-access-token>" 
    -H "Content-Type: application/json" 
    -d '{
          "notificationId": "PortfolioCreatedWebhook",
          "displayName": "SeedPortfolioWithCash",
          "description": "A webhook notification that seeds a portfolio with cash when the 'portfolio created' event occurs",
          "notificationType": {
            "Type": "Webhook",
            "HttpMethod": "Post",
            "Url": "/api/api/transactionportfolios/{{Body.portfolioScope}}/{{Body.portfolioCode}}/transactions",
            "AuthenticationType": "Lusid",
            "ContentType": "Json",
            "Content": [
              {
                "transactionId": "TransactionId-111111",
                "type": "StockIn",
                "instrumentIdentifiers": {
                    "instrument/default/ClientInternal": "TestEquity",
                },
                "transactionDate": "{{Header.timestamp}}",
                "settlementDate": "{{Header.timestamp}}",
                "units": 1000,
                "transactionPrice": {
                    "price": 123,
                    "type": "Price"
                },
                "totalConsideration": {
                    "amount": 123000,
                    "currency": "GBP"
                },
                "transactionCurrency": "GBP"
              } ]
          }
       }'
    The response is as follows. Note you can use the notificationId of the notification (highlighted in red) to reference it again in subsequent API calls: 
    {
  "notificationId": "PortfolioCreatedWebhook",
  "displayName": "SeedPortfolioWithCash",
  "description": "A webhook notification that seeds a portfolio with cash when the 'portfolio created' event occurs",
  "notificationType":
    "Content": [
      {
        "transactionId": "TransactionId-111111",
        "type": "StockIn",
        "instrumentIdentifiers": {
          "instrument/default/ClientInternal": "TestEquity"
        },
        "transactionDate": "{{Header.timestamp}}",
        "settlementDate": "{{Header.timestamp}}",
        "units": 1000,
        "transactionPrice": {
          "price": 123,
          "type": "Price"
        },
        "totalConsideration": {
          "amount": 123000,
          "currency": "GBP"
        },
        "transactionCurrency": "GBP"
      }
    ],
    "type": "Webhook",
    "httpMethod": "Post",
    "url": "/api/api/transactionportfolios/{{Body.portfolioScope}}/{{Body.portfolioCode}}/transactions",
    "authenticationType": "Lusid",
    "contentType": "Json",
  },
  "createdAt": "2023-07-14T08:44:28.3039366+00:00",
  "userIdCreated": "00u91lo2d7X42sdse2p7",
  "modifiedAt": "2023-07-14T08:44:28.3039366+00:00",
  "userIdModified": "00u91lo2d7X42sdse2p7",
  "href": "https://<your-domain>.lusid.com/notification/api/subscriptions/PortfolioEvents/PortfolioCreatedEvent/notifications/PortfolioCreatedWebhook"
}

Using the LUSID web app

<Coming soon>

Keywords: notification service, webhook