Providing you are a LUSID user with sufficient access control permissions, you can create a webhook notification to call a third party (that is, non-LUSID) API when an event you have subscribed to occurs. For example, your webhook could call the Atlassian Create issue API to create a JIRA when the LUSID PortfolioCreated
event occurs.
Note the following:
You must have already subscribed to the event you want to attach the webhook notification to.
You can only call API endpoints that use
PUT
,POST
orDELETE
verbs.You do not have access to API responses, so calls to API endpoints that get or list data 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 LUSID API.
Using the Notification REST API
Currently, you can create one notification per API call.
Upload your credentials for the third party API to the Configuration Store. This can either be a Bearer Token or a Basic Authentication username and password.
Obtain an API access token for the operations below.
Call the CreateNotification API, passing in your API access token and:
The
scope
andcode
of the subscription to attach it to.A
displayName
and uniquenotificationId
.A
Type
ofWebhook
.A
HttpMethod
of eitherPUT
,POST
orDELETE
.A
Url
that constitutes a full path to the resource, for examplehttps://acmecorp.atlassian.net/rest/api/3/issue
.An
AuthenticationType
of eitherBearerToken
if the receiving service supports OAuth 2.0, or elseBasicAuth
.An
AuthenticationConfigurationItemPaths
object that specifies the path to the access token or basic authentication credentials uploaded to the Configuration store. For example, to reference a bearer token uploaded toexternal-services/jira
in the Personal area of the Configuration Store:"BearerToken": "config://personal/00u91lo2d7X42sdse88/external-services/jira/api-token"
If the token scheme is not
Bearer
, use theBearerScheme
key to locate an appropriate scheme uploaded to the Configuration Store.
To reference Basic Authentication credentials uploaded to the same location:"Username": "config://personal/00u91lo2d7X42sdse88/external-services/jira/username", "Password": "config://personal/00u91lo2d7X42sdse88/external-services/jira/password"
To find out the exact syntax of a
config://
path, call the Configuration Store GetConfigurationItem API for that item.A
ContentType
ofJson
.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 codePortfolioCreated
. 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/PortfolioCreated/notifications" -H "Authorization: Bearer <your-API-access-token>" -H "Content-Type: application/json" -d '{ "notificationId": "PortfolioCreatedJiraWebhook", "displayName": "PortfolioCreatedWebhookNotification", "description": "Create JIRA for new portfolio", "notificationType": { "Type": "Webhook", "HttpMethod": "Post", "Url": "https://acmecorp.atlassian.net/rest/api/3/issue", "AuthenticationType": "BearerToken", "AuthenticationConfigurationItemPaths": { "BearerToken": "config://personal/00u91lo2d7X42sdse88/external-services/jira/api-token" }, "ContentType": "Json", "Content": { "update": {}, "fields": { "summary": "Portfolio with ID {{Body.portfolioScope}}/{{Body.portfolioCode}} created on {{Header.timestamp}} - action required", "parent": { "key": "PROJ-123" }, "issuetype": { "id": "10000" } } } } }'
The response is as follows. Note you can use the
id
of the notification to reference it again in subsequent API calls:{ "notificationId": "PortfolioCreatedJiraWebhook", "displayName": "PortfolioCreatedWebhookNotification", "description": "Create JIRA for new portfolio", "notificationType": { "ContentType": "Json", "Content": { "update": {}, "fields": { "summary": "{{PortfolioName}} with ID {{PortfolioScope}}/{{PortPortfolio}} created on {{PortfolioCreated}} - action required", "parent": { "key": "PROJ-123" }, "issuetype": { "id": "10000" } } }, "type": "Webhook", "httpMethod": "Post", "url": "https://acmecorp.atlassian.net/rest/api/3/issue", "authenticationType": "BearerToken", "authenticationConfigurationItemPaths": { "BearerToken": "config://personal/00u91lo2d7X42sdse88/external-services/jira/api-token" } }, "createdAt": "2023-07-21T13:59:58.2881300+00:00", "userIdCreated": "00u91lo2d7X42sdse2p7", "modfiedAt": "2023-07-21T13:59:58.2881300+00:00", "userIdModified": "00u91lo2d7X42sdse2p7", "href": "https://<your-domain>.lusid.com/notification/api/subscriptions/PortfolioEvents/PortfolioCreated/notifications/PortfolioCreatedJiraWebhook" }
Using the LUSID web app
<Coming soon>