Creates a new subscription.

POST {{baseUrl}}/api/notifications/subscriptions

Once a subscription is created, Unity API collects notifications for the subscription in an internal mailbox and keeps them for up to a few days. This mailbox can be accessed through the fetch API using so called positions. 1. To start consuming event notifications for your subscription, create an initial position via the position API function. The position can be at the beginning of the mailbox (where the oldest item is located), at a certain date, at the most recent notification, or at the end of the mailbox. 2. Then use the fetch API to query notifications from the created position. The API function fetches available notifications from that position and returns a new position (NextPosition response value) which has been moved by exactly the number of notifications it returned in its response. 3. For subsequent fetch calls, pass in the provided NextPosition value from the previous call in order to continue reading new notifications. Make sure to leave some time between fetch calls in case no more notifications are available from the provided position, which is indicated in the response of the fetch call (MoreAvailable response value).

Note that Unity API only keeps notifications for a certain number of days. Any notifications older than that will be discarded and can no longer be fetched, even if you create a position that starts at the beginning of the mailbox or at an earlier date.

You can create and use multiple subscriptions for the same domain and event types. Refer to these subscriptions using their subscription identifier to independently receive event notifications. Likewise, you can also create and use multiple positions for the same subscription, if needed.

Note for webhook-based subscriptions: Subscriptions can be used in combination with a publicly accessible webhook API endpoint which is under your control. By registering a webhook API endpoint using the DeliveryType webhook for your subscription, Unity API will call the endpoint whenever new notifications become available on the subscription. Consuming notifications that are available in the subscription's mailbox is still done at your discretion through the same means as with fetch-based subscriptions. The webhook enables listening for arriving notifications and fetching notifications on-demand rather than having to speculatively query the fetch API at regular intervals.

When creating a webhook-based subscription, a synchronous validation call to the webhook DeliveryUrl will be made. The webhook has to respond successfully and with the expected ValidationResponse value in the response (the value must match the ValidationContext value provided in the webhook request). Otherwise the subscription will not be created and an error is returned.

See the webhook section in the Notifications Guide and its subchapter about Webhook Calls: Validation Message for more information.

Request Body

{"DeliveryType"=>"webhook", "Domain"=>{"Type"=>"Site", "Values"=>[{"Name"=>"GSMKey", "Value"=>"9DBB-69AA-B1BE-462F-9E5F"}, {"Name"=>"SiteKey", "Value"=>"0CA9-0FCA-C423-4C01-AC4A"}]}, "EventTypes"=>["Endpoint.FileDetection"], "Webhook"=>{"DeliveryContext"=>"MyCustomCorrelationString", "DeliveryRateInSeconds"=>90, "DeliveryUrl"=>"https://my.company.com/wrunity/notifications/webhook"}}

HEADERS

RESPONSES

status: OK

{"SubscriptionId":"e326db5b-45b8-4d4b-9d91-63ab47ede0bf","DeliveryType":"webhook","Domain":{"Type":"Site","Values":[{"Name":"GSMKey","Value":"3013-B66E-CBE9-4C51-85ED"},{"Name":"SiteKey","Value":"DD52-1B7D-1AEB-4719-B08A"}]},"EventTypes":["Endpoint.FileDetection"],"Webhook":{"DeliveryContext":"MyCustomCorrelationString","DeliveryRateInSeconds":90,"DeliveryUrl":"https://my.company.com/wrunity/notifications/webhook","Suspended":false,"Statistics":null},"CreatedDate":"2022-08-29T10:36:07.0286531Z","UpdatedDate":null}