Documentation

Mistake on this page? Email us

The event notification channel

The event notification channel is a data pipe through which Pelion Device management delivers events to your web application. The events are delivered in a NotificationMessage and your web application has two options to form the notification channel to receive the messages. You can either use the callback interface where Device Management sends a NotificationMessage as a request to your service. Alternatively, you can use the WebSocket interface where you open a web socket. Device Management pushes the following events thorough the event notification channel:

  • Registration and deregistration events, as well as registration expiration.
  • Notifications from subscribed Resources.
  • Proxy request results.

Note: Every single notification channel is bound to the API key of an application. If two different application instances uses the same API key, they overwrite the notification channel, which would cause them to miss all notifications.

Callback interface

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

To set a callback URL:

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

  2. Device Management Connect verifies the callback URL by calling PUT with the given headers (headers are optional).

  3. The web application responds with 200 OK

  4. Device Management Connect stores the callback URL for the specific API key.

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

  5. When an event occurs, Device Management Connect sends notifications 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.

Callback interface.

Securing the callback channel

To secure the callback channel, you need to provide a HTTPS callback URL. Device Management Connect presents a certificate signed by a trusted certificate authorithy (GlobalSign) with a Common Name (CN) set to notifications.mbedcloud.com when sending a request to the callback URL.

To validate the Device Management Connect certificate, you need to add the chain of trust from the GlobalSign root certificate in the customer's server:

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

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

WebSocket interface

(PREVIEW) Use /v2/notification/websocket to set up a WebSocket interface. The WebSocket interface does not wait for an application level ACK but sends the next patch when the transport level has succeeded.

To set up the WebSocket:

  1. The web application calls PUT /v2/notification/websocket to create the channel.
    1. Subscribed events are received immediately when the channel is registered. The events bundle is delivered once the socket is eventually opened.
    2. If the WebSocket is closed but the channel remains, it keeps receiving and storing messages until the WebSocket is connected again or for 24 hours, after which the channel will be removed.
    3. When opening the channel, its status is disconnected and it 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 API 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 API key and accepts the WebSocket, returning with HTTP status 101 Switching Protocols (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 automatically after 24 hours of inactivity, or if an error occurs. Closing the socket from client closes the channel, too.

WebSocket interface

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 will attempt 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').

The server may close the WebSocket for various reasons. The close frame contains a WebSocket close status code along with a reason (string). Possible reasons for closing the socket from the server are:

Status code Reason Description
1000 Normal close Socket closed by client.
1001 Going away If the channel is deleted with a REST call or the server is shutting down or if a WebSocket is already opened with the given API key, the first created socket will be closed with this code.
1006 Abnormal close The connection is lost without either party sending the close frame. This code is never set by the notification service.
1008 Policy violation Authentication fails due to an invalid or missing API key header when connecting.
1011 Unexpected condition No channel has been registered for this API key with a prior PUT when connecting.
1011 Along with an appropriate reason string, this code indicates any unexpected closing of the WebSocket by the server.

The following example demonstrates connecting to the WebSocket channel using 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");
};

Pull interface

The pull notification method is replaced by WebSocket interface and will be removed from the service.

Notification sending logic

Notifications are delivered 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, as while the batch is in delivery, the notification queue size grows and the next batch of notifications is larger.

The same logic applies to the pull interface: when a new pull request is sent, Device Management Connect responds with a batch of notifications.

If the notification batch sending fails, Device Management tries to resend with progressive back off of 2 s, 4 s, 8 s, 16 s… up to 2 minutes. If the sending does not succeed within 24 hours, the event notification channel will be closed.

Notification items are cached for 24 hours in a queue of up to 50,000 items, so it is possible to lose notifications if Device Management cannot deliver for a while.

The diagram shows the notification process:

  1. The application server is notified of a batch of 100 observations.
  2. New observations are received and added to the queue.
  3. Same as step 2.
  4. There is no response to the notification and therefore, Device Management Connect resends after one second. The new batch is formed from the changing queue, so it contains different data:
    • The oldest observation Obs-1 exceeds the lifetime and is removed from the queue. It will not be included in the batch.
    • The new observations Obs-101 and Obs-102 are added to the queue. They are included in the batch, because adding them does not exceed the maximum size.

Notification batch resending logic