POST /service/api/notifications/subscriptions
Creates a new subscription.
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.
- 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.
- 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.
- 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.
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 Information
URI Parameters
None.
URI Sample(s)
POST
|
https://unityapi.webrootcloudav.com/service/api/notifications/subscriptions
|
Body Parameters
Information about the subscription to be created, specifying domain information and one or multiple event types.
CreateSubscriptionRequestModelName | Description | Type | Additional Information |
---|---|---|---|
DeliveryType |
The delivery type of the subscription. Valid values are: "fetch" or "webhook". Fetch-based subscriptions are consumed at your discretion by creating and maintaining a position value which is used to query your notifications for a subscription from the "mailbox" store. See the position and fetch APIs for more information. Webhook-based subscriptions allow registering an API endpoint under your control to receive HTTPS calls informing about new notifications becoming available in the "mailbox" store. Calls to your webhook API endpoint only inform about new notifications and do not contain notification details. Consuming notifications is still done at your discretion through the same means as with fetch-based subscriptions. The webhook enables "listening" for arriving notifications in your subscriptions' mailbox and fetching notifications on-demand when they become available instead of having to speculatively query the fetch API at regular intervals. |
string |
Required |
Domain |
The desired domain to subscribe for notifications which matches the specified event types. Please note that all event types you subscribe to must support the chosen domain. |
CreateSubscriptionRequestModelDomain |
Required |
EventTypes |
The list of event types to subscribe to. |
Collection of string |
Required |
Webhook |
Defines webhook related properties. |
CreateSubscriptionRequestModelWebhook |
Required, if DeliveryType is "webhook". |
Sample Request
{ "DeliveryType": "webhook", "Domain": { "Type": "Site", "Values": [ { "Name": "GSMKey", "Value": "FC2A-0627-28FA-4D98-ACBB" }, { "Name": "SiteKey", "Value": "25C3-BF85-C048-4430-A1E8" } ] }, "EventTypes": [ "Endpoint.FileDetection" ], "Webhook": { "DeliveryContext": "MyCustomCorrelationString", "DeliveryRateInSeconds": 90, "DeliveryUrl": "https://my.company.com/wrunity/notifications/webhook" } }
<CreateSubscriptionRequestModel xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://schemas.datacontract.org/2004/07/Webroot.UnityAPI.ServiceExtension.Notifications.Models"> <DeliveryType>webhook</DeliveryType> <Domain> <Type>Site</Type> <Values> <CreateSubscriptionRequestModelDomainValue> <Name>GSMKey</Name> <Value>FC2A-0627-28FA-4D98-ACBB</Value> </CreateSubscriptionRequestModelDomainValue> <CreateSubscriptionRequestModelDomainValue> <Name>SiteKey</Name> <Value>25C3-BF85-C048-4430-A1E8</Value> </CreateSubscriptionRequestModelDomainValue> </Values> </Domain> <EventTypes xmlns:d2p1="http://schemas.microsoft.com/2003/10/Serialization/Arrays"> <d2p1:string>Endpoint.FileDetection</d2p1:string> </EventTypes> <Webhook> <DeliveryContext>MyCustomCorrelationString</DeliveryContext> <DeliveryRateInSeconds>90</DeliveryRateInSeconds> <DeliveryUrl>https://my.company.com/wrunity/notifications/webhook</DeliveryUrl> </Webhook> </CreateSubscriptionRequestModel>
Response Information
Resource Description
Information about the newly created subscription.
CreateSubscriptionResponseModelName | Description | Type | Additional Information |
---|---|---|---|
SubscriptionId |
The subscription identifier. |
string |
None. |
DeliveryType |
The delivery type of the subscription. |
string |
None. |
Domain |
The domain the subscription has been created for. |
SubscriptionResponseModelDomain |
None. |
EventTypes |
The list of subscribed event types. |
Collection of string |
None. |
Webhook |
Information about webhook properties set for the subscription. This value is null, if DeliveryType is anything other than "webhook". |
SubscriptionResponseModelWebhook |
None. |
CreatedDate |
The time when the subscription was created. |
date |
None. |
UpdatedDate |
The time when the subscription was last updated. |
date |
None. |
Sample Response
{ "SubscriptionId": "05da40b1-7232-49dd-95b6-c432d447ac17", "DeliveryType": "webhook", "Domain": { "Type": "Site", "Values": [ { "Name": "GSMKey", "Value": "FF8D-96AB-760F-48A7-8115" }, { "Name": "SiteKey", "Value": "15B6-DB87-CEDF-4F4F-8963" } ] }, "EventTypes": [ "Endpoint.FileDetection" ], "Webhook": { "DeliveryContext": "MyCustomCorrelationString", "DeliveryRateInSeconds": 90, "DeliveryUrl": "https://my.company.com/wrunity/notifications/webhook", "Suspended": false, "Statistics": null }, "CreatedDate": "2024-09-02T11:07:40.8245709Z", "UpdatedDate": null }
<CreateSubscriptionResponseModel xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://schemas.datacontract.org/2004/07/Webroot.UnityAPI.ServiceExtension.Notifications.Models"> <CreatedDate>2024-09-02T11:07:40.8245709Z</CreatedDate> <DeliveryType>webhook</DeliveryType> <Domain> <Type>Site</Type> <Values> <SubscriptionResponseModelDomainValue> <Name>GSMKey</Name> <Value>FF8D-96AB-760F-48A7-8115</Value> </SubscriptionResponseModelDomainValue> <SubscriptionResponseModelDomainValue> <Name>SiteKey</Name> <Value>15B6-DB87-CEDF-4F4F-8963</Value> </SubscriptionResponseModelDomainValue> </Values> </Domain> <EventTypes xmlns:d2p1="http://schemas.microsoft.com/2003/10/Serialization/Arrays"> <d2p1:string>Endpoint.FileDetection</d2p1:string> </EventTypes> <SubscriptionId>05da40b1-7232-49dd-95b6-c432d447ac17</SubscriptionId> <UpdatedDate i:nil="true" /> <Webhook> <DeliveryContext>MyCustomCorrelationString</DeliveryContext> <DeliveryRateInSeconds>90</DeliveryRateInSeconds> <DeliveryUrl>https://my.company.com/wrunity/notifications/webhook</DeliveryUrl> <Statistics i:nil="true" /> <Suspended>false</Suspended> </Webhook> </CreateSubscriptionResponseModel>