Documentation

Mistake on this page? Email us

The event notification channel

To receive notification messages from device events, the web application needs to provide a callback interface. Device Management Connect pushes the following events to the callback interface:

  • 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 callbak URL fails continuously for 24 hours, the callback channel is removed. Please 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 will present 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, the chain of trust from the GlobalSign root certificate should be added 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: The verification depth of the client certificates chain should be configured to 2 at least.

Pull interface

The pull notification method is deprecated and is for development only. It will be replaced with different technology.

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 Connect sends a new 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 Connect tries to resend after 1 second, 2s, 4s, 8s, 16s… up to 2 minutes. If the sending does not succeed within 24 hours, the callback URL is removed along with all queued notifications. Subscriptions are not removed but the web application needs to set the callback URL again when operational.

Notification items are cached for one hour in a queue of up to 50,000 items, so it is possible to lose notifications if the callback URL is unavailable for longer than one hour or the queue gets filled up.

The diagram shows a 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. Because there is no response to the notification, 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 has been removed from the queue, and thus will not be included in the batch.
    • The new observations Obs-101 and Obs-102 have been added to the queue. They are included in the batch, because adding them does not exceed the maximum size.

Notification batch resending logic