Filter results by

Subscribe and notify

In the WebSockets documentation, we explain how your application or device can use one of two WebSocket types to:

  • Listen to messages sent by devices or applications that interest you.
  • Receive messages targeted to your devices or applications.

However, WebSockets may not be your best solution, due to one of the following reasons:

  • You cannot use WebSockets. For example, your application framework may not provide you such an option.
  • Maintaining a WebSocket connection (which is primarily for high-frequency messages) is not worthwhile. For example, you might be expecting a low frequency of messages (including Actions).

To support these use cases, ARTIK Cloud provides subscription and notification services for your applications or devices (called clients in this document).

A client calls an API to create a subscription to ARTIK Cloud, and then receives notifications on pertinent messages or Actions through callbacks. The high-level workflow is illustrated below.

ARTIK Cloud Subscription highlevel

In the subscription, the client specifies the message type for which it wants to be notified (messages or Actions), a filter (for a user and any specific devices or device types), and additional configurations (callback URL, batching of notifications, etc).

Every time a message or Action is available in ARTIK Cloud that matches the criteria defined in the subscription, ARTIK Cloud calls the callback URL of the client to notify it.

The client can later unsubscribe by calling an API to delete the subscription.

The subscription and notification functionality can be used to send data from ARTIK Cloud to an Amazon Kinesis Stream in real-time. See Push to Amazon Kinesis.

Subscribe to ARTIK Cloud

ARTIK Cloud Subscription sequence diagram

The above subscription sequence diagram is divided into two phases:

  1. Creating a subscription (Steps 1-3).
  2. Confirming a subscription (Steps 4-7).

The subscription object

When APIs are called to create, get, or delete a subscription, ARTIK Cloud returns the subscription as a JSON object in the HTTP response, as below:

1
2
3
4
5
6
7
8
9
10
11
12
13
{ 
   "data":{ 
      "id":"1673d8888883acfcc50c9d",
      "aid":"f9c82b97b788888b7e2",
      "messageType":"message",
      "uid":"2455g888888",
      "description":"This is a subscription to a user's devices",
      "callbackUrl":"https://callback.example.com:443/messages?user=earl1234",
      "status":"ACTIVE",
      "createdOn":1435191843948,
      "modifiedOn":1439489593485
   }
}

Let's take a closer look at the subscription object.

Subscription fields

The below tables indicate which request parameters are mandatory when creating a subscription.

Field Description Notes
subscriptionType Specify if the subscription is for a callback URL (default) or an Amazon Kinesis Stream. Can be httpCallback or awsKinesis.

See below tables for additional required parameters for each type.
id Subscription ID. Returned upon creation.  
aid Client ID associated with the subscription. Derived from the access token.  
messageType Type of message to subscribe to. Required for subscription creation.

Can be message or action.
uid User ID to subscribe to. This will notify for all user-owned devices that have granted permissions to the client. Required for subscription creation.
sdtid Source device type ID to subscribe the user to. This will notify for all user-owned devices of this device type. Message type must be message.

Client must have been granted READ for this device type.

Can't be specified with sdid.
sdid Source device ID to subscribe to. Message type must be message.

Client must have been granted READ for this device's device type.

Can't be specified with sdtid.
ddid Destination device ID to subscribe to. Used when listening for Actions. Required for subscription creation if the message type is action.
description Description of the subscription. Intended for display purposes.  
status Status of the subscription. Can be PENDING_CALLBACK_VALIDATION or ACTIVE.
createdOn Timestamp that the subscription was created. In milliseconds since epoch. READ-ONLY.
modifiedOn Timestamp that the subscription was last modified. In milliseconds since epoch. READ-ONLY.

You can include sdtid or sdid when listening for message type message.
You must include ddid when listening for message type action.

Subscription fields (HTTP callback only)

Field Description Notes
callbackUrl Callback URL to be used. Can include query parameters. Required for subscription creation.

Must be HTTPS and use a valid X.509 certificate from a well-known certificate authority (may not use a self-signed certificate).

Create a subscription

At Step 1 of the subscription sequence, the client makes an HTTP POST call to create a subscription.

POST /subscriptions

Refer to the table of subscription fields to determine which parameters you should include in your request body.

In the below example request, the client intends to receive notifications from ARTIK Cloud when devices owned by the specified user ID send a message of type message to ARTIK Cloud.

1
2
3
4
5
6
{ 
   "messageType":"message",
   "uid":"2455g88888",
   "description":"This is a subscription to a user's devices",
   "callbackUrl":"https://callback.example.com:443/messages?user=earl1234"
}

Port is restricted to 443 in the callback URL when subscribing.

The access token provided in the POST call must have at least READ permissions over the devices. This is obtained through the application permissions (scope) configured in the Developer Dashboard. Either application or user tokens can be used with this POST call. To learn more about these token types, click here.

Each notification is delivered by calling the callbackUrl defined in the request.

At Step 2 of the subscription sequence, ARTIK Cloud validates the callback URL in the request to ensure it has the same domain as the application redirect URL. (Recall that you provided the redirect URL when creating an application in the Developer Dashboard.)

ARTIK Cloud compares the top two levels of the two domains. For example, when comparing "notifications.callback.company.com" with "redirect.company.com", validation will pass since both URLs end in "company.com". Validation does not use the protocol and port in the URL. If validation of the callback URL fails, no subscription will be created (Step 3.1).

In a successful case, ARTIK Cloud creates a subscription with status PENDING_CALLBACK_VALIDATION at Step 3.2. ARTIK Cloud changes the subscription status to ACTIVE if the subscription is confirmed within 24 hours (see the following section).

ARTIK Cloud will delete this subscription if it is not confirmed within 24 hours.

Confirm a subscription

Confirming a subscription comprises Steps 4 to 7 in the subscription sequence.

At Step 4, ARTIK Cloud makes the following HTTP POST call to the callback URL of the client.

POST <callback url>

The request has the following JSON payload in the body:

1
2
3
4
5
{
   "aid": "<CLIENT ID>",
   "subscriptionId": "<SUBSCRIPTION ID>",
   "nonce": "<NONCE>"
}

The client callback endpoint should be open and not require authentication or authorization.

The client retrieves the subscription ID and the nonce from the above HTTP request.

(ARTIK Cloud ignores the HTTP response from the client at Step 5.)

At Step 6 of the subscription sequence, the client makes the following HTTP POST call to ARTIK Cloud to confirm the subscription.

POST /subscriptions/:subscriptionID/validate

The request should contain the following JSON payload in the body:

1
2
3
4
{
   "aid": "<CLIENT ID>",
   "nonce": "<NONCE>"
}

ARTIK Cloud does not authenticate this HTTP POST call. Therefore an access token is not required in the call.

After receiving the above HTTP request as the confirmation, ARTIK Cloud changes the subscription status from PENDING_CALLBACK_VALIDATION to ACTIVE.

At Step 7, ARTIK Cloud sends the HTTP response with the subscription JSON object to the client. This completes the subscription process.

Receive notifications from ARTIK Cloud

Upon receving a notification at the callback URL, the client authenticates it and then extracts a notification ID. It retrieves messages related to this notification by making follow-up GET calls to ARTIK Cloud.

The following diagram illustrates how a client handles a notification.

ARTIK Cloud notification sequence diagram

Authenticate notifications

In Step 1 of the notification sequence, ARTIK Cloud sends an authenticated POST request to the client's callback URL. The request is built based on Making Requests in OAuth 1.0.

The client should verify that each ARTIK Cloud notification is from ARTIK Cloud, and the authorization header of the request contains the necessary information. Here is an example header:

1
2
3
4
5
6
7
Authorization   OAuth oauth_consumer_key="f32cb82256184b2ea0c4ab30ee08186b",
                oauth_nonce="2981717297499358590",
                oauth_signature="8zA9B5yjIOQcNyhOi%2Fz%2BoxgITOM%3D", 
                oauth_signature_method="HMAC-SHA1", 
                oauth_timestamp="1443815778", 
                oauth_token="f32cb82256184b2ea0c4ab30ee08186b", 
                oauth_version="1.0"

The client follows Verifying Requests in OAuth 1.0 to verify the request.

ARTIK Cloud only implements Authenticated Requests instead of the full OAuth 1.0 workflow. During notification authentication, ARTIK Cloud acts as an OAuth 1.0 client and an ARTIK Cloud client acts as an OAuth 1.0 server.

Steps 2 to 4 of the notification sequence follow OAuth 1.0 request verification. At Step 2, the client follows Signature to verify oauth_signature in the authorization header of a received request. The client compares the signature generated locally with the one received. It uses the following information when generating the signature locally:

1
2
3
4
consumer key = CLIENT ID
consumer secret = CLIENT SECRET
token = CLIENT ID
token secret = CLIENT SECRET

Recall that CLIENT ID and CLIENT SECRET for your ARTIK Cloud application can be found on the Developer Dashboard.

Handle the notification payload

After an ARTIK Cloud notification passes authentication, the client extracts the notification ID from the payload. This is Step 5 of the notification sequence.

In the below example, id is the notification ID.

1
2
3
4
5
6
7
8
9
{
  "id": "4e8ab4fda0a444d1876099e3ad3sb77e",   
  "ts": 1434754443650,
  "type": "action",
  "subscriptionId": "dd66b5a1b35c428a8ede4966db73s1d9",
  "subscriptionQuery": {"uid":"johndoe", "ddid":"frontdoor_hue"},
  "startDate": 1434754443630,
  "endDate": 1434754443630
}

Notification payload fields

Parameter Description
id Notification ID.
ts Timestamp that the notification was created, in milliseconds since epoch.
type Message type. Can be message or action.
subscriptionId Subscription ID.
subscriptionQuery Subscription query.
startDate Timestamp of the first message, in milliseconds since epoch.
endDate Timestamp of the last message, in milliseconds since epoch.

Note that startDate and endDate will be identical if a notification contains only one message.

Get messages in a notification

The client makes HTTP GET calls to get the messages associated with the notification ID extracted from the notification payload.

GET /notifications/<notificationID>/messages

Refer to the notification API reference for the details of the request and response. Below is an example response containing a message.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
{ 
  "order":"asc",
  "total":1,
  "offset":0,
  "count":1,
  "data":[ 
    { 
       "mid":"057a407d4f814cbc874f3f7a0485af3b",
       "data":{ 
         "dateMicro":1421281794211000,
         "ecg":-73
       },
       "ts":1421281794212,
       "sdtid":"dtaeaf898b4db941gba",
       "cts":1421281794212,
       "uid":"7b202300eb904149b36e9739574s62a5",
       "mv":1,
       "sdid":"4697f11336c540a69ffd6s445061215e"
    }
  ]
}

Due to notification batching, one notification could include multiple messages sent within a short time period. Since one GET call can only return a maximum of 100 messages, it is the client's responsibility to use a proper algorithm to retrieve all messages associated with one notification.

For example, the client could check if count in the response reaches the maximum number. If so, it then tracks the accumulative count of messages received for this notification and makes another GET call with the same notification ID, but with the increased offset value. Specifically, the offset value (which starts at 0) is equal to the accumulative count. The client repeats this process until count is less than 100.

Batch notifications

To avoid flooding a client with a large number of notifications, ARTIK Cloud queues notifications for each subscription based on the following principles:

  • If a notification is triggered by a message with type action, it is sent to the client immediately.
  • If a notification is the first notification of a given subscription, it is sent immediately.
  • For subsequent notifications for the same subscription, ARTIK Cloud queues them. Every 30 seconds, ARTIK Cloud aggregates all notifications arrived in this time period into one notification, and sends this notification to the client. This means sending a notification for message type message could be delayed up to 30 seconds after ARTIK Cloud detects the triggering event.

Two types of callbacks

There are two separate cases where ARTIK Cloud makes HTTP POST calls to a client callback URL. The client is responsible for differentiating them.

Below are two suggestions for differentiating the ARTIK Cloud requests: