How do I create a webhook to call a LUSID API when an event occurs?

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 PortfolioCreated 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.

Obtain an API access token for the operations below.

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 API reference 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 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 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