Event notification channel

Event notification channel is a data pipe from Device Management to a web application. Subscribed events or asynchronous response events are delivered through it. It provides a queueing and delivery mechanism that ensures event delivery in case of temporary connectivity issues or load spikes.

The events are delivered in a NotificationMessage. Your web application has two options to form a notification channel to receive the messages:

• Use the callback interface. Device Management sends a NotificationMessage as a request to your service.
• Use the WebSocket interface to open a web socket.

Device Management pushes the following events through the event notification channel:

Properties

Note: Every notification channel is bound to the API key of an application. If two different application instances use the same API key, the application that sets the channel last overrides the previous one.

Callback interface

To register a callback interface, use /v2/notification/callback. 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.

Securing the callback channel

To secure the callback channel, you must provide an HTTPS callback URL. The HTTPS protocol will encrypt all the data flowing from Device Management to your application, making it unintelligible for a potential interceptor.

The HTTPS protocol alone is not enough to secure the communication channel. There are two other factors that you should consider to ensure the callback channel security:

• Ensure the data is coming from source that you can rely on (from Device Management). For that purpose, Device Management Connect presents a certificate signed by a trusted certificate authority (GlobalSign) with a Common Name (CN) set to notifications.mbedcloud.com when sending a request to the callback URL. This certificate should be validated.

  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 set the verification depth of the client certificates chain to 2 at least.

• Ensure the data is coming from a source you have authorized. You need to include an optional authorization header during the callback channel creation.

  If you added the authorization header during the channel creation, it will be included in all callback requests and you can authorize the requests based on it.

WebSocket interface

To set up a WebSocket interface, use /v2/notification/websocket. The WebSocket interface does not wait for an application level ACK but sends the next patch when the transport level has succeeded.

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

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.

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:

Note: You must implement reconnection logic. The server may close connections in the cases of load balancing, service restart, or software update. The client should try to reconnect after a short delay for codes 1006 and 1012.

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");
};

Configuring the channel

You can configure the channel according to your needs. For example, you can use the device's endpoint name instead of the device ID for the events. Read more about device identity.

For the channel configuration options, see v2/notification/callback and v2/notification/websocket.

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.

On rare occasions, callback and websocket channels may receive duplicate notifications. You can configure the callback and websocket channels to contain a message identifier for each notification. Use it to detect duplicates. See channel serialization configuration for more details.