Documentation - Notifications

New! Event Notifications

The Unity API platform enables you to query for a broad set of data relating to Webroot's eCommerce service, endpoint protection product, and global site manager console. Although ad-hoc information is very useful for presenting the current state of the ecosystem to users on demand, reacting to status change is difficult without being alerted about important state transitions. This is the purpose of the Unity API Event Notification feature.

Event Notifications allow you to subscribe to a set of events on different domain levels, and to receive the associated notifications in near real-time. The following subchapters introduce the different aspects of the event notification functionality and provide more detailed information about currently available Event Types, Notification Domains, and Delivery Mechanisms.

Adding support and improvements for additional event types, notification domains and delivery mechanisms is constantly monitored and reviewed by the Unity API and Product teams. Future releases will incorporate these features as the Unity API evolves.

How to enable Notifications?

Event notifications functionality is provided as part of API methods which are grouped under the Notifications.Subscriptions API scope. Permission to this scope is NOT automatically granted and you need to enable notifications or request access.

If you have a Webroot Management Console account for managing your Global Site Manager (GSM) consoles, notifications can be enabled with just a few steps by creating new or modifying existing API Access client credentials.

Log in with your console account at my.webrootanywhere.com and choose a Global Site Manager console.
Then navigate to Settings -> API Access.
Click the New button to create new client credentials.
Alternatively, enable notifications on existing client credentials by selecting a client ID and clicking the Edit button.
Enter the requested information and make sure to answer Yes for the Do you plan to use the event notification API? question.
The NOTIFICATION API column indicates whether notifications is enabled for a given client ID.
Authenticate with Unity API using your notifications-enabled client credentials to get access to near real-time event notifications.

If you are a Webroot eCommerce/distribution partner and want to enable notifications on your assigned Unity API client credentials, please contact your trusted Webroot representative for getting started.

Event Types

The following list of event types are currently supported and can be subscribed to:

Event Type	Applicable Scopes	Supported Domains	Description
Endpoint.FileDetection	Console.GSM, SkyStatus.GSM, SkyStatus.Site	GSM, Site	Event that is triggered when the WSA client detects a (potentially) malicious file.
WebThreatShield.UrlAction	Console.GSM	GSM, Site	Event that is triggered when Web Threat Shield (WTS) acts on a URL.

Note: When subscribing to event notifications, your authentication token needs to have access to the Notifications.Subscriptions scope. Additionally, the authentication token needs to have access to at least one of the scopes listed in the Applicable Scopes column. In case you subscribe to multiple event types in a single subscription, the token needs to have access to one of the scopes of each chosen event type.

Notification Domains

Notification Domains are different levels at which event types can be subscribed to. For example, see the table below for the domains supported by the Endpoint File Detection event type:

Domain Name

Required Values

Description

GSM

	GSMKey
	The GSM parent keycode.

Provides file detection event notifications for endpoints managed by any site on a given GSM console.

Site

	GSMKey
	The GSM parent keycode.

	SiteKey
	The keycode of the GSM site.

Provides file detection event notifications for endpoints managed by a specific GSM site.

When creating a subscription, all values listed in the chosen domain's Required Values column need to be provided in the request body. For example, when subscribing to notifications for the Site domain, the values in the request body should be provided as follows:

{
    ...
    "Domain": {
        "Type": "Site",
        "Values": [
            { 
                "Name": "GMSKey", 
                "Value": "ABCD-EFGH-IJKL-NMOP-QRST",
            },
            {
                "Name": "SiteKey",
                "Value": "1234-5678-9012-3456-7890"
            }
        ]
    },
    ...

Note: If you subscribe to multiple event types in a single subscription, all chosen event types must support the selected domain level.

Delivery Types

Currently, Unity API supports two types of delivery: fetch and webhook. The following sections describe both types.

Fetch Delivery Type

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 a "mailbox" store.

Delivery Type	Method	API	Description
Fetch	GET	/service/api/notifications/subscriptions/{subscriptionId}/fetch?position={position}	A lightweight request to fetch the latest available notifications that are related to a given subscription.

Webhook Delivery Type

Webhook-based subscriptions allow registering an API endpoint under your control to receive HTTPS calls informing about new notifications 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 subscription's mailbox and fetching notifications on-demand when they become available instead of having to speculatively query the 'fetch' API at regular intervals.

The address of the URL to be called by Unity API is specified when a new subscription of delivery type 'webhook' is created. Here is what happens then:

During creation of the new subscription, Unity API checks the validity of the specified webhook URL using an HTTPS POST call.
If the webhook call returns a success code within a certain time period, the subscription function proceeds with the next step. Otherwise it fails.
Unity API instructs its internal Event Filtering System to watch out for subscription related events, so that they can be collected for later retrieval.
Finally, the subscription function returns a success code to the user.
Whenever there are new events for the subscription, the webhook URL specified above is called to inform that there are new notifications available.
The program code of the webhook uses the 'fetch' API (preferably in an asynchronous operation) for retrieving and processing the new notifications.

The webhook URL endpoint must meet the following requirements:

It must be publicly reachable and must support the HTTPS protocol
It must respond to a pre-defined HTTPS POST call within a timely fashion
It must support UTF8
The certificate of the web server must
- not be self-signed
- not be expired
- not be revoked
- be signed by a trusted authority
- meet the condition of the certificate’s subject matching the hostname.

Responsiveness of Webhooks

Notification related webhooks are expected to complete within 10 seconds. Depending on the message type, failure to comply with this requirement will be treated differently:

Validation calls which do not respond in a timely fashion will cause the currently pending subscription request to fail.
Notification calls which do not return a success code within a timely fashion or which return a 5xx error will trigger retries. Should none of these retry calls succeed, the respective subscription will be suspended. Suspended subscriptions can be resumed via a Resume Webhook call.

Webhook Calls: Validation Message

Unity API sends out HTTPS POST validations (to the URL specified in the respective subscription) in four cases to check the correctness of a given URL:

A webhook subscription is created
A subscription is changed from “fetch” to “webhook” (Edit Subscription)
The DeliveryUrl field or the DeliveryContext field of a webhook subscription is modified (Edit Subscription)
A suspended webhook subscription is resumed as per a user’s request (Resume Webhook)

Validation calls can be recognized by checking the Type field for “Validation”.

Validation Request Body Example:

{
  "SubscriptionId": "61223a5f-23c3-fbd2-acc3-01fc7ba2118d",
  "Type": "Validation",
  "DeliveryContext": "24412AF",
  "ValidationContext": "12F3AF56"
}

Fields:

SubscriptionId: Id of the subscription this call relates to (not available in validation messages triggered by Create Subscription requests).
Type: The actual activity. This can be:
- “Validation“: used when Unity API checks the validity of a webhook.
DeliveryContext: A length limited textual field which was provided when creating the subscription and which is transmitted with every webhook call.
ValidationContext: A textual field which the webhook is expected to return in the response body to demonstrate its validity.

Both SubscriptionId and DeliveryContext will remain the same in subsequent calls for the same subscription. Webhooks may store these for later usage.

Note: The Validation context concept is intended to validate if the right URL was specified.

Validation Response Body Example:

The response must reflect what has been passed over in the ValidationContext field:

{
  "ValidationResponse": "12F3AF56"
}

Note: If no response body is returned or if there is no ValidationResponse field in the response body which corresponds with the ValidationContext field that was passed over, the associated subscription call will fail.

Content Type and Response Status Codes

Unity API will pass “application/json“ as the content type when calling a webhook. The encoding used is UTF-8. Any 2xx status code will be treated as a success. Any non 2xx status code will be treated as a failure which causes the pending subscription call to fail as well. Validations will not be retried. If they fail, a subscription will either not be created or edited at all or it will not be resumed.

Note: For new subscriptions the SubscriptionId field will be empty/will not exist, since the subscription has technically not been created yet. This only affects validation messages triggered by CreateSubscription calls. Validation requests initiated by EditSubscription as well as messages of type “Notifications“ will always have a valid SubscriptionId field.

Webhook Calls: Notification Message

Whenever new notifications are available for a specific subscription and the DeliveryRateInSecond field which was provided in the subscription indicates that the next call is due, the webhook specified in the respective subscription will be called (HTTPS POST action).

Notification calls can be recognized by checking the Type field for “Notifications”

Notifications Call Request Body Example:

{
  "SubscriptionId": "7754244a-545b-4ae1-9eeb-f05b016f517e",
  "Type": "Notifications",
  "DeliveryContext": "12470XN"
}

Fields:

SubscriptionId: Id of the subscription this call relates to.
Type: The actual activity. This can be:
- “Notifications“: signals that new notifications are available to be fetched.
DeliveryContext: A length limited textual field which was provided when creating the subscription and which is transmitted with every webhook call.

Notifications Call Response Body Example:

Any data that is returned to Unity API will be ignored.

Content Type and Response Status Codes

Unity API will pass “application/json“ as the content type when calling a webhook. The encoding used is UTF-8. Any 2xx status code will be treated as a success. A 5xx status code will trigger a retry at a later stage, unless the maximum number of retries has exceeded a certain threshold (similar to a timeout). Any other error code will lead to an immediate suspension of the subscription.

Note: If a notification call fails with an HTTP status code of 5xx or does not return in a timely fashion (within 10 seconds), Unity API will retry to reach the webhook multiple times.

Note: Once the retry count for a notification message exceeds a certain threshold, the subscription will be suspended. In this case, Unity API will no longer call the webhook to inform about new notifications. Subscriptions in such a state can be resumed by calling the Resume Webhook function. The suspension state of a subscription can be queried via Get Subscription.

Note: When resuming subscriptions, Unity API will start sending notification messages after the ResumeSubscription command has finished (if the validation call succeeded). Webhooks will not receive messages that occurred between the suspension and the reactivation of a subscription.

About the Delivery Context

The delivery context is a user defined value which can be used for reference purposes in the webhook. This may be useful as an additional context value for lookup purposes in addition to the subscription identifier, and as an added layer of security for verifying the source of the webhook caller.

Rules and Requirements

Subscriptions to event notifications are governed by specific rules and requirements, and users need to follow certain guidelines and recommendations. See the list below for more information:

When subscribing to multiple event types at once, all chosen events must support the same subscription domain.
The authenticated user who is subscribing to and consuming event notifications must have access to the resource that is associated with the specified domain.
The authenticated user who is subscribing to and consuming event notifications must have access to the Notifications.Subscriptions scope and to at least one of the applicable scopes per chosen event type.
An authenticated user can create multiple subscriptions, even for the same set of event types, subscription domains, and associated resources (e.g. the GSM console or sites).
The lightweight 'fetch' API can be called frequently, but it should still be used in moderation. For an individual subscription, querying for notifications once per minute is considered a reasonable frequency. If this is not sufficient, consider using webhooks for getting called back on new notifications instead.
When subscriptions are no longer needed, users are highly encouraged to unsubscribe every unused subscription.
Idling subscriptions, for which event notifications have not been consumed longer than e.g. 30 days, will be unsubscribed automatically and will no longer be accessible to the original subscriber. When needed again, the affected subscriptions need to be re-created by the user. The time period until a subscription is deemed idle remains at the discretion of the Unity API platform team and is subject to change.
Different types of events can have different time delays between the time when the event occurs and the time when the event notification is made available for consumption. The delay can be up to multiple minutes.
An event notification represents a point-in-time information and does not indicate the effective state of the resource when the notification is available. For example, when a notification is received that an endpoint detected an infection, it may not mean that the endpoint is still infected. If it is required to know the effective state of the endpoint, it is recommended to subsequently query the most recent Endpoint Status or Console Status information for that endpoint.
When fetching notifications, it is the caller's responsibility to keep track of their subscriptions' position values and pass them in accordingly for subsequent calls. If, for some reason, a subscription's position value is lost, a new position can be created at certain stage markers. See the Create Position API method for more information.

Example Steps using Fetch

The following steps show how to subscribe to event notifications, create an initial starting point for consuming notifications, fetch available event notifications, and finally unsubscribe from the subscription.

Step 1: First choose the event types and the domain you want to subscribe to

See the event types list and the domains list above for more information about available options.

Alternatively, make a call to the Get Event Types API method to receive a list of available event types.

Method	API	Description
GET	/service/api/notifications/subscriptions/eventtypes	Gets a list of available event types that can be subscribed to, with information on required scope permissions and subscription domains for each event type.

Note: Ensure to adjust the API request URL to match the Unity API environment you intend to call. The base path for this environment for example is https://unityapi.webrootcloudav.com.

Step 2: Make a POST request to the subscriptions API to create a subscription

Method	API	Description
POST	/service/api/notifications/subscriptions	Creates a new subscription.

Step 3: Identify your desired starting position for consuming event notifications

Unity API stores notifications for a subscription in an internal mailbox. This mailbox can be accessed via so called position tokens. If you do not have a position token yet for a given subscription, you can create one via the following call. Subsequently, when querying event notifications you will receive new position tokens that advance the position for your subscription's mailbox. Use these new position tokens to continue querying for event notifications.

Method	API	Description
POST	/service/api/notifications/subscriptions/{subscriptionId}/position	Generates a position token which can be used to start fetching notifications.

To start querying event notifications, you can create different types of position tokens depending on your needs. Please see the documentation of the Create Position API method for more information.

Step 4: Use the delivery API for consuming event notifications

Delivery Type	Method	API	Description
Fetch	GET	/service/api/notifications/subscriptions/{subscriptionId}/fetch?position={position}	Retrieves the latest notifications for a specific subscription.

Step 5: Use the NextPosition from the response for consuming additional event notifications

When fetching event notifications, the response will include notification records, if available, and a NextPosition value. Use this value to continue querying for further notifications on your subscription. Re-using your starting position or any previous position values will result in getting older notifications multiple times and eventually prevents you from moving forward in the notifications history.

In Step 4 we received a NextPosition value as shown below. Use this value for the subsequent call to the delivery API.

"NextPosition": "Krudcyu7nXN2eJxhqV_YCAI-BAAAAAAAYzg0MjViMzgtMzg3MS00NWQ5LTk5MGYtZGY4YzhmMjE4NTk4"

Delivery Type	Method	API	Description
Fetch	GET	/service/api/notifications/subscriptions/{subscriptionId}/fetch?position={position}	Retrieves the latest notifications for a specific subscription.

Please note that the response in this case did not return any further notifications. It also shows that the provided NextPosition is the same as the one specified in the request. This is a valid scenario, but it is not guaranteed that position values remain the same when there are no more notifications available. Always make sure to collect the NextPosition value from the response and specify it in your subsequent request.

Step 6: When notifications for your subscription are no longer needed, unsubscribe from the subscription

Method	API	Description
DELETE	/service/api/notifications/subscriptions/{subscriptionId}	Unsubscribes from a specific subscription.

Example Steps using Webhooks

The following steps show how to subscribe to event notifications via webhooks and finally unsubscribe from the subscription.

Step 1: First choose the event types and the domain you want to subscribe to

See the event types list and the domains list above for more information about available options.

Alternatively, make a call to the Get Event Types API method to receive a list of available event types.

Method	API	Description
GET	/service/api/notifications/subscriptions/eventtypes	Gets a list of available event types that can be subscribed to, with information on required scope permissions and subscription domains for each event type.

Note: Ensure to adjust the API request URL to match the Unity API environment you intend to call. The base path for this environment for example is https://unityapi.webrootcloudav.com.

Step 2: Make a POST request to the subscriptions API to create a subscription

Method	API	Description
POST	/service/api/notifications/subscriptions	Creates a new subscription.

Step 3: Identify your desired starting position for consuming event notifications

Method	API	Description
POST	/service/api/notifications/subscriptions/{subscriptionId}/position	Generates a position token which can be used to start fetching notifications.

To start querying event notifications, you can create different types of position tokens depending on your needs. Please see the documentation of the Create Position API method for more information.

Step 4: Use the delivery API for consuming event notifications

When your webhook URL is called, this indicates that new notifications for your subscription are available. Notifications are not passed to the webhook URL directly but your code behind needs to use the fetch notifications call (see below) to retrieve the latest notifications.

Note: You should not fetch notifications directly in the code implementing your webhook URL action but rather offload processing to some background worker process. This process should receive a trigger, every time the webhook is called. This design ensures that your webhook implementation returns in the shortest possible time, thus avoiding webhook calls queueing up and potentially failing.

Delivery Type	Method	API	Description
Fetch	GET	/service/api/notifications/subscriptions/{subscriptionId}/fetch?position={position}	Retrieves the latest notifications for a specific subscription.

You must store the NextPosition value you received and use it for subsequent call to the delivery API if the webhook is triggered next time.

"NextPosition": "Krudcyu7nXN2eJxhqV_YCAI-BAAAAAAAYzg0MjViMzgtMzg3MS00NWQ5LTk5MGYtZGY4YzhmMjE4NTk4"

Step 5: When notifications for your subscription are no longer needed, unsubscribe from the subscription

Method	API	Description
DELETE	/service/api/notifications/subscriptions/{subscriptionId}	Unsubscribes from a specific subscription.