Documentation

Mistake on this page? Email us

Setting a notification channel

Setting a notification channel enables you to receive data from devices to the application of your choice.

When you set a notification channel, and when you subscribe to a resource or send the device a command, you provide your application's access key. Device Management knows which device data to send to which notification channel based on this application key.

You can register a callback URL or a WebSocket as your callback channel.

Device Management delivers notifications in batches of up to 10,000 items. When the web application responds with 200 OK to the current notification batch, Device Management sends the next batch. The web application should respond quickly, because the next batch of notifications is accumulating in the queue during the delivery of the current batch.

Note: When you upgrade from a free tier to a commercial tier account, Device Management does not update notification channels automatically. The limits listed on Account types and limits page apply until you delete your channels and register them again. You can use the same access key when re-registering the notification channel.

Setting up callback notifications

Registering a callback notification channel

To set up a callback notification channel:

  1. Register the callback URL using the /v2/notification/callback PUT API.

    You can also use /v2/notification/callback to define optional headers. For example, you can set an authorization header with a token, or provide additional information to your web application.

  2. Integrate the Device Management CA into your application to enable the application to authenticate communication with the Device Management.

    For the application to validate the Device Management certificate, you need to add the chain of trust from the GlobalSign root certificate to the application server:

    • GlobalSign Root CA - R3

      • Subject: OU=GlobalSign Root CA - R3, O=GlobalSign, CN=GlobalSign
      • SHA1 fingerprint: D6:9B:56:11:48:F0:1C:77:C5:45:78:C1:09:26:DF:5B:85:69:76:AD
    • GlobalSign Organization Validation CA - SHA256 - G2

      • Subject: C=BE, O=GlobalSign nv-sa, CN=GlobalSign Organization Validation CA - SHA256 - G2
      • SHA1 fingerprint: EF:90:B2:B8:6F:47:56:EB:E7:D3:6F:F3:01:5D:63:52:3A:00:76:E9
    • The Device Management server CA.

Note: You need to set the verification depth of the client certificates chain to 2 at least.

Device Management presents a certificate signed by a trusted certificate authority (GlobalSign) with a Common Name (CN) set to notifications.mbedcloud.com when Device Management sends a request to the callback URL. Your application can also validate the certificate common name.

Integrating an application with Device Management for callback notifications

This diagrams shows the communication between Device Management and the application server during the callback notification flow:

Callback interface

  1. The web application calls PUT /v2/notification/callback and provides the callback URL in the body.

    Note: The callback URL in the web application must be publicly available to be accessed by Device Management.

  2. Device Management verifies the callback URL by placing a PUT call with the given headers (headers are optional).

  3. The web application responds with 200 OK.

  4. Device Management stores the callback URL for the specific access key.

    Note: Each access key can only have one callback URL. If you set another callback URL with the same access key, the first URL will be overwritten.

  5. When an event occurs, Device Management sends notification messages to the callback URL, with the given headers.

    Note: If sending to the callback URL fails continuously for 24 hours, the callback channel is removed. See Notification sending logic.

Setting up WebSocket notifications

Registering a WebSocket notification channel

To set up a WebSocket notification channel:

  1. Use the /v2/notification/websocket PUT API to register a WebSocket notification channel.

    Note: A single WebSocket channel can deliver a few thousand events per second.

    The notification channel begins receiving subscribed events immediately. However, the application only receives the event bundle after the application opens the socket.

  2. Use the /v2/notification/websocket-connect GET API to open the socket and get notifications.

Integrating an application with Device Management for WebSocket notifications

This diagrams shows the communication between Device Management and the application server during the WebSocket notification flow:

WebSocket interface

  1. The web application calls PUT /v2/notification/websocket to create the channel.
    • The notification channel begins receiving subscribed events immediately when the application registers the channel. Device Management delivers the event bundle when the application opens the socket.
    • If the WebSocket is closed but the channel is registered, the channel continues to receive and store messages until the WebSocket is connected again or for 24 hours, after which Device Management removes the socket.
    • When you open the channel, its status is disconnected. The status changes to connected whenever the channel has an active WebSocket bound to it.
  2. The web application calls GET /v2/notification/websocket-connect. The web application must provide the access key used in the previous step, in the Sec-WebSocket-Protocol header, or as a bearer token in the Authorization header if the WebSocket client supports it.
  3. Device Management verifies the access key and accepts the WebSocket, returning a 101 Switching Protocols HTTP status (most WebSocket libraries handle this handshake transparently).
  4. Device Management pushes notification events to the socket until the client or server closes it. The server closes the socket automatically after 24 hours of inactivity, or if an error occurs. Closing the socket from the client closes the channel, too.

Note: Device Management will ping your web service to keep the connection open. Most clients can handle the pings automatically. If the ping frame is not responded within a few seconds, the connection is considered lost and the server attempts closing the WebSocket with code 1001 (Going away), including a message about the ping timeout. The ping frame from the server consists of four bytes which the server expects the client to echo in the response frame ('pong').

This is an example of how to connect to the WebSocket channel using the HTML5 WebSocket API from a browser:

var socket = new WebSocket("wss://<HOST>/v2/notification/websocket-connect", ["wss", "pelion_{API_KEY}"]);

socket.onopen = function(event) {
  console.log("WebSocket opened");
};

socket.onmessage = function(event) {
  console.log("Notification received: " + event.data);
};

socket.onerror = function(err) {
  console.log("Error occurred");
};

socket.onclose = function(event) {
  console.log("WebSocket closed");
};