Documentation

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.

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

CreateSubscriptionRequestModel

Name	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": "1B29-D4BD-F1B5-423E-B62F"
      },
      {
        "Name": "SiteKey",
        "Value": "F021-8090-CED7-4229-B781"
      }
    ]
  },
  "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>1B29-D4BD-F1B5-423E-B62F</Value>
      </CreateSubscriptionRequestModelDomainValue>
      <CreateSubscriptionRequestModelDomainValue>
        <Name>SiteKey</Name>
        <Value>F021-8090-CED7-4229-B781</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.

CreateSubscriptionResponseModel

Name	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": "e7457ec7-d495-41f6-914d-f7b759b26114",
  "DeliveryType": "webhook",
  "Domain": {
    "Type": "Site",
    "Values": [
      {
        "Name": "GSMKey",
        "Value": "4694-501E-8FFD-4F44-82AA"
      },
      {
        "Name": "SiteKey",
        "Value": "6319-0506-F80C-4DD9-92D3"
      }
    ]
  },
  "EventTypes": [
    "Endpoint.FileDetection"
  ],
  "Webhook": {
    "DeliveryContext": "MyCustomCorrelationString",
    "DeliveryRateInSeconds": 90,
    "DeliveryUrl": "https://my.company.com/wrunity/notifications/webhook",
    "Suspended": false,
    "Statistics": null
  },
  "CreatedDate": "2024-09-21T17:23:00.5685977Z",
  "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-21T17:23:00.5685977Z</CreatedDate>
  <DeliveryType>webhook</DeliveryType>
  <Domain>
    <Type>Site</Type>
    <Values>
      <SubscriptionResponseModelDomainValue>
        <Name>GSMKey</Name>
        <Value>4694-501E-8FFD-4F44-82AA</Value>
      </SubscriptionResponseModelDomainValue>
      <SubscriptionResponseModelDomainValue>
        <Name>SiteKey</Name>
        <Value>6319-0506-F80C-4DD9-92D3</Value>
      </SubscriptionResponseModelDomainValue>
    </Values>
  </Domain>
  <EventTypes xmlns:d2p1="http://schemas.microsoft.com/2003/10/Serialization/Arrays">
    <d2p1:string>Endpoint.FileDetection</d2p1:string>
  </EventTypes>
  <SubscriptionId>e7457ec7-d495-41f6-914d-f7b759b26114</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>