---
title: "How do I create a webhook to call a LUSID API when an event occurs?"
slug: "how-do-i-create-a-webhook-to-call-a-lusid-api-when-an-event-occurs"
tags: ["notification service ", "webhook"]
updated: 2025-08-01T13:10:25Z
published: 2025-08-01T13:10:25Z
canonical: "support.lusid.com/how-do-i-create-a-webhook-to-call-a-lusid-api-when-an-event-occurs"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://support.lusid.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/v1/docs/understanding-all-the-applications-in-the-finbourne-platform)) 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](/v1/docs/using-a-webhook-to-automatically-seed-new-portfolios-with-cash).

Note the following:

- You must have already [subscribed to the event](/v1/docs/how-do-i-subscribe-to-an-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](/v1/docs/how-do-i-create-a-webhook-to-call-a-third-party-api-when-an-event-occurs).

## Using the Notification REST API

Currently, you can create one notification per API call.

1. [Obtain an API access token](/v1/docs/how-do-i-obtain-and-use-a-short-lived-api-access-token-from-okta) for the operations below.
2. Call the [CreateNotification](https://www.lusid.com/docs/api/notification/endpoints/notifications/CreateNotification/) API for your LUSID domain, passing in your API access token and:

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](/v1/docs/using-mustache-templates-to-enrich-notifications) as placeholders for values generated by the event each time it occurs:

```json
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:

```json
{
  "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"
}
```
  - The `scope` and `code` of the [subscription](/v1/docs/how-do-i-subscribe-to-an-event) 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](https://www.lusid.com/docs/api/lusid/endpoints/instruments/UpsertInstruments) API. Note the double `/api/api/` is intentional in the core LUSID API.
    - `/drive/api/files` to call the Drive [CreateFile](https://www.lusid.com/docs/api/drive/endpoints/files/CreateFile) API.
  - An `AuthenticationType` of `Lusid`.
  - A `ContentType` of `Json`.
  - A `Content` object that contains the expected payload for the API.