Documentation

Mistake on this page? Email us

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.

Event notification channel

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

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

Event Description
Device registration, deregistration and expiration events. By default, sent on any device in the account.
Notifications from subscribed Resources. When a subscribed Resource changes, a device sends an event to Device Management. If a channel matching the subscribing API key is found, Device Management delivers the event to that channel.
Proxy request results. Asynchronous responses to the device's Resource operations are delivered to a web application.

Properties

Property Limit Description
Queue size 50 MB The queue for one API key channel is limited to 50 MB. Reliable storage has some overhead for every stored notification. As an example, an event of 100 bytes can have more than 160,000 messages in the queue before the oldest ones are deleted.
Event lifetime 24 hours Events Device Management has received more than 24 hours ago will be removed from the queue. You can use the event timestamp to see how old items there are in the queue and whether your system is keeping up with the event speed.
Channel idle timeout 48 hours If there is no data coming in within 48 hours, the queue is removed. You will need to establish a new channel to start receiving events.
Delivery fail timeout 24 hours Device Management tries to deliver events for 24 hours. If the remote end does not respond during that time, the channel is deleted.
Batch size limit 10,000 events (default) Even one event in the queue triggers notification sending. The events come in batches of 1-10,000 depending on the number of events in the queue. You can adjust this with the max_chunk_size configuration.
Events in a second ~ 1000 events in a second The callback channel can receive and deliver approximately 1000 events in a second.

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.

Callback interface

Securing the callback channel

To secure the callback channel, you need to provide an HTTPS callback URL. 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.

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.

WebSocket interface

(PREVIEW) 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: Websocket can deliver around 50 events in a 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.

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 a close frame. This code is never set by Device Management.
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.
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");
};

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.

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.