Skip to main content
Version: v5.1

Subscriptions

Overview#

A subscription usually associates a given device with a group of interested users, ensuring that they get notified by email whenever certain system events occur.

As well as device type subscriptions, the Notification Service also supports webhook type subscriptions. With webhooks, an application developer can set up a subscription directly to a given URL.

Notifications are then sent, based on matching the device transport type with a sender of the same transport type, and templates with the same transport type.

The device user can typically manage their subscription based on the notifications sent to them. For example, for an EMAIL type subscription, the email address owner must first accept notifications by responding to a link in an email. Notifications can include unsubscribe links that the email address owner user can follow.

Types of subscriptions#

There are two different types of subscription:

  • Device type subscriptions: A device type subscription associates a given device with a group. Notifications are sent based on matching the device transport type with a sender of the same transport type, and templates with the same transport type. The device end user can (typically) manage their subscription based on the notifications sent to them, for example, for an EMAIL type subscription, the email address owner must first accept notifications by responding to (following a link in) an email, and notifications can include unsubscribe links that the email address owner user can follow.

  • Webhook type subscriptions: A webhook type subscription defines a webhook that will be called when a notification is sent to a particular group. Note that a webhook subscription does not require a device, nor a sender. Webhooks subscriptions are managed only through Notification Service APIs. When the group is matched, the URL is called with the API details defined in the subscription, and using an optional authorization method.

Subscription properties#

Main properties#

When you create a subscription, the following properties are supported:

  • _namespaces: A string array, which must contain a single item, which must match the namespace of the referenced group.
  • _group._id: The ID of the group to which this subscription relates. _ _type: Must be either DEVICE or WEBHOOK

DEVICE properties#

When _type is DEVICE, the following properties are supported:

  • _device._id: The ID of the device to which this subscription relates.

WEBHOOK properties#

When _type is WEBHOOK, the following properties are supported:

  • _webhook._method: The HTTP method (For example, POST, PUT, etc.)
  • _webhook._url: Target URL for the webhook
  • _webhook._query: Query string key/values (optional)
  • _webhook._headers: Header key/values (optional)
  • _webhook._authorization._id: The ID of an Authorization entity (optional)
  • _webhook._body: Velocity template for the webhook body.

Note: Once a subscription is created, all webhook-specific properties can be edited. However, the subscription type itself cannot be changed.

From get or list subscription requests, the read-only property _status is available. It shows the current status of the subscription, which will be one of the following values:

  • CREATED: The subscription has been created and will automatically transition to either REQUESTED or ACCEPTED, depending on the subscription type and transport type.
  • REQUESTED: Confirmation has been requested from the end user.
  • ACCEPTED: Confirmation has been received from the end user, or the subscription type and transport type did not require confirmation.
  • CANCELLED: The end-user has cancelled the subscription. For example, when a users clicks the cancel link in an email.

Using the Subscription API#

This section lists some useful examples of using the Notification Service API to perform operations with subscriptions.

For a full reference to the Subscription API, refer to the Subscription Rest API page.

How to create a device subscription#

To create a device type subscription, refer to the sample code below.

const subscription = await IafNotification.createSubscription({    _namespaces: project._namespaces,    _type: "DEVICE",    _group: {        _id: group.id    },    _device: {        _id: device.id    }}, ctx);

How to create a webhook subscription#

To create a webhook type subscription, refer to the sample code below.

const subscription = await IafNotification.createSubscription({    _namespaces: project._namespaces,    _type: "WEBHOOK",    _group: {      _id: group.id    },    _webhook: {       _method: "POST",       _url: "http://example.com",       _headers: {           "Content-Type": "application/json"       },       _authorization: {           _id: authorization.id       },       _body: "{\"status\":\"OK\"}"    }}, ctx);

For a more detailed description of setting up a webhook subscription, refer to the How to set up a webhook subscription page.

How to list subscriptions#

To list subscriptions, you must provide a query. The query must include at a minimum, a set of namespaces for which the calling user has READ permission.

The following query properties are supported, which map to the same properties used when creating subscriptions:

  • namespaces
  • device.id
  • group.id

To list all the subscriptions in your project, refer to the sample code below. 

const subscriptions = await IafNotification.listSubscription({    namespaces: project._namespaces}, ctx);

How to delete a subscription#

To delete a subscription, refer to the sample code below. 

await IafNotification.deleteSubscription(subscription._id, ctx);