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.


Property Limit Description
Queue size 50 MB The queue for one API key channel is limited to 50MB. A 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. If the queue size limit is exceeded, the oldest events in the queue are removed to stay within the limited size.
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 50-20,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.
Event sending retry limit Commercial - no limits
Free-tier - limits apply
For a commercial account, event resending is not limited. The event lifetime and queue size apply.
For free-tier accounts, the retry limitations are:
Web socket channel - No limit
Callback channel - Sending is limited to one. If sending fails, next batch is sent.

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

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.
1012 Server restart Set, for example, when the server is balancing load between nodes, restarting for update, or being maintained. The client should reconnect after receiving this status code. A short reconnect delay is recommended.

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: " +;

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.

Account tier transition

If you upgrade an account from free tier to commercial tier, notification channels are not updated automatically. The limits listed on Account types and limits page apply until you delete the channels and register them again after the transition using the Notifications API. You can use the same API key when re-registering the notification channel.