Documentation

Mistake on this page? Email us

Notifications API

Pelion Device Management Notifications API allows web applications to register a channel for receiving notifications from devices. Please read notification sending logic for more details on notification channels. See Troubleshooting the APIs for information on status and error codes.
Version: 2
Host: https://api.us-east-1.mbedcloud.com

Endpoints

DeviceDataNotifications

get /v2/notification/websocket-connect
Open the websocket. Show more Show less

A websocket channel can have only one active connection at a time. If a websocket connection for a channel exists and a new connection to the same channel is made, the connection is accepted and the older connection is closed.

A websocket client library should be used when connecting to this endpoint.

Once the socket has been opened, the server may close it with one of the following status codes.

Code Description
1000 Socket closed normally by the client, or by the server when the channel is deleted with a REST call.
1001 Going away. Set when another socket opens on the used channel.
1006 Abnormal closure. The client should reconnect after receiving this status code. A short reconnect delay is recommended.
1008 Policy violation. Set if the API key is lost or invalidated after a successful WebSocket handshake.
1011 Unexpected condition. The socket is closed with this status in an attempt to open a socket to a nonexistent channel (without a prior PUT request). This code is also used to indicate a closing socket for any other unexpected condition in the server.
1012 Service restart. Set when the server restarts for update, maintenance, and so on. The client should reconnect after receiving this status code. A short reconnect delay is recommended.

Expected client behaviour:

If the connection is closed with code 1006 or 1012, the client should try to reconnect to maintain the notification flow. The client might disconnect several times in a relatively short period, for example, during service updates. This is normal. The desired client behavior is to reconnect after each disconnect.

Example:

curl -X GET https://api.us-east-1.mbedcloud.com/v2/notification/websocket-connect \
-H "Authorization:Bearer {apikey}" \
-H "Connection:upgrade" \
-H "Upgrade:websocket" \
-H "Sec-WebSocket-Version: 13" \
-H "Sec-WebSocket-Key: {base64nonce}" \
-N -I
Request headers
Connection (required)
Header Parameter — default: Upgrade
Upgrade (required)
Header Parameter — default: websocket
Sec-WebSocket-Protocol (optional)
Header Parameter — API key or user token must be present in the Sec-WebSocket-Protocol header if Authorization header cannot be provided: Sec-WebSocket-Protocol:"wss,pelion_ak_{api_key}". Refer to the notification service documentation for examples.
Origin (required)
Header Parameter — Originating host of the request.
Sec-WebSocket-Version (required)
Header Parameter — WebSocket version. Must be 13. default: 13
Sec-WebSocket-Key (required)
Header Parameter — The value of this header field must be a nonce consisting of a randomly selected 16-byte value that has been base64-encoded (see Section 4 of [RFC4648]). The nonce must be selected randomly for each connection.
Responses
status description schema
101 Switching protocols.
400 Required header(s) missing.
401 Unauthorized.
426 Upgrade required. Connect and/or Upgrade headers missing.
429 While a WebSocket handshake is still in progress, no new WebSocket requests with the same authorization token will be accepted.
delete /v2/notification/pull
Delete notification Long Poll channel. Show more Show less
Deprecation Date:
Expected End of Life:
Long polling is deprecated and should be used for development purposes only.
Links:

Delete a notification Long Poll channel. This is required to change the channel from Long Poll to another type. Do not make a GET /v2/notification/pull call for two minutes after deleting the channel, because it can implicitly recreate the pull channel. You can also have some random responses with payload or 410 GONE with "CHANNEL_DELETED" as a payload or 200/204 until the old channel is purged.

Example:

curl -X DELETE https://api.us-east-1.mbedcloud.com/v2/notification/pull \
-H 'Authorization: Bearer <api_key>'
Responses
status description schema
200 Success. The body can contain "REMOVED" if it was deleted with this call or "ALREADY_DELETED" if it was deleted before and not purged yet.
401 Unauthorized.
delete /v2/notification/websocket
Delete websocket channel. Show more Show less

Delete a notification websocket channel bound to the API key. This is required to change the channel from websocket to another type.

Deleting the websocket channel also removes the channel's notification queue. Any unsent notifications are lost when the channel is deleted. Example:

curl -X DELETE https://api.us-east-1.mbedcloud.com/v2/notification/websocket \
-H 'Authorization: Bearer <api_key>'
Responses
status description schema
204 Successfully deleted.
401 Unauthorized.
403 Forbidden. The authorization token used is not an API key.
404 Websocket channel doesn't exist.
delete /v2/notification/callback
Delete callback URL. Show more Show less

Deletes the callback URL.

Deleting the callback URL also removes the channel's notification queue. Any unsent notifications are lost when the channel is deleted.

Example:

curl -X DELETE https://api.us-east-1.mbedcloud.com/v2/notification/callback \
-H 'Authorization: Bearer <api_key>'
Responses
status description schema
204 Successfully deleted.
401 Unauthorized.
403 Forbidden. The authorization token used is not an API key.
404 Callback URL does not exist.
get /v2/notification/channel
Get channel metadata. Show more Show less

Get channel delivery mechanism.

Example:

curl -X GET https://api.us-east-1.mbedcloud.com/v2/notification/channel \
-H 'Authorization: Bearer <api_key>' \
Return type
Example data
Content-Type: application/json
{
  "delivery_mechanism" : "CALLBACK"
}
Responses
status description schema
200 Success. ChannelMetadata
404 Channel was not found.
get /v2/notification/callback
Check callback URL. Show more Show less

Shows the current callback URL if it exists.

Example:

curl -X GET https://api.us-east-1.mbedcloud.com/v2/notification/callback \
-H 'Authorization: Bearer <api_key>'
Return type
Example data
Content-Type: application/json
{
  "serialization" : "{}",
  "headers" : "{\"authorization\" : \"f4b93d6e-4652-4874-82e4-41a3ced0cd56\"}",
  "url" : "https://www.example.com/my-webhook"
}
Produces
This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.
  • application/json
Responses
status description schema
200 URL found. Webhook
401 Unauthorized.
403 Forbidden. The authorization token used is not an API key.
404 The callback URL does not exist.
get /v2/notification/websocket
Get websocket channel information. Show more Show less

Returns 200 with websocket connection status, if websocket channel exists.

Example:

curl -X GET https://api.us-east-1.mbedcloud.com/v2/notification/websocket \
-H 'Authorization: Bearer <api_key>'
Return type
Example data
Content-Type: application/json
{
  "serialization" : "{}",
  "queue_size" : 0,
  "status" : "disconnected"
}
Produces
This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.
  • application/json
Responses
status description schema
200 Websocket found. WebsocketChannel
401 Unauthorized.
403 Forbidden. The authorization token used is not an API key.
404 No channel has been registered.
get /v2/notification/pull
Get notifications using Long Poll Show more Show less
Deprecation Date:
Expected End of Life:
Long polling is deprecated and should be used for development purposes only.
Links:

In this case, notifications are delivered through HTTP long poll requests. The HTTP request is kept open until one or more event notifications are delivered to the client, or the request times out (response code 204). In both cases, the client should open a new polling connection after the previous one closes. Only a single long polling connection per API key can be ongoing at any given time. We recommend using a persistent connection (Connection keep-alive header in the request) to avoid excess TLS handshakes.

The pull channel is implicitly created by the first GET call to /v2/notification/pull. It refreshes on each GET call. If the channel is not polled for a long time (10 minutes), it expires and is deleted. This means that no notifications will stay in the queue between polls. A channel can be also be deleted explicitly with a DELETE call.

Note: If you cannot have a public-facing callback URL, for example, when developing on your local machine, you can use long polling to check for new messages. However, long polling is deprecated and will likely be replaced in the future. It is meant only for experimentation, not commercial use. The proper method to receive notifications is a notification callback.

There can only be one notification channel per API key in Device Management Connect. If a notification channel of other type already exists for the API key, delete it before creating a long poll notification channel.

Example:

curl -X GET https://api.us-east-1.mbedcloud.com/v2/notification/pull \
-H 'Authorization: Bearer <api_key>'
Return type
Example data
Content-Type: application/json
{
  "registrations" : [ {
    "q" : false,
    "original-ep" : "my-device-123",
    "ept" : "Light",
    "resources" : [ {
      "path" : "/sen/light",
      "ct" : "text/plain",
      "obs" : true,
      "rt" : "light_sensor",
      "if" : "sensor"
    } ],
    "ep" : "015f3850a657000000000001001002ab"
  } ],
  "reg-updates" : [ "" ],
  "async-responses" : [ {
    "ct" : "text/plain",
    "payload" : "My4zMQ==",
    "max-age" : "60",
    "id" : "9e3c96b8-c4d7-496a-ab90-cc732b9b560e",
    "error" : "TIMEOUT",
    "status" : 200
  } ],
  "notifications" : [ {
    "path" : "/sen/light",
    "ct" : "text/plain",
    "payload" : "My4zMQ==",
    "max-age" : "60",
    "ep" : "015f3850a657000000000001001002ab"
  } ],
  "de-registrations" : [ "015f3850a657000000000001001002ab" ],
  "registrations-expired" : [ "015f3850a657000000000001001002ab" ]
}
Produces
This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.
  • application/json
Responses
status description schema
200 Success. NotificationMessage
204 No new notifications.
400 Other type of channel already exists.
401 Unauthorized.
409 Conflict. Long poll request exists already.
410 Pull channel was deleted and waiting to be purged. This code is a result of incorrect client behavior (delete channel and then pull), which can prevent the creation of a callback channel after the pull channel is deleted. The channel can be (randomly) recreated by this call when deleted and not purged. This client behaviour can set the channel in an undefined state for some time. The channel may respond with 410 GONE or 200/204 codes randomly for some time. Finally, the channel enters a valid "channel exists" state.
put /v2/notification/callback
Register a callback URL. Show more Show less

Register a URL to which the server delivers notifications of changes to the subscribed resource. To push notifications, you must first place subscriptions. The maximum length of the URL, header keys, and values, all combined, is 400 characters.

Notifications are delivered as PUT requests to the HTTP server, which the client defines with a subscription server message. The given URL must be accessible, and respond to the PUT request with a response code of 200 or 204.

Device Management Connect tests the callback URL with an empty JSON payload {} when the URL is registered. Callback implementation does not support URL redirection. For more information on notification messages, see NotificationMessage.

Optional headers in a callback message:

You can set optional headers to a callback in a Webhook object. Device Management Connect includes the header and key pairs in the notification messages send them to callback URL. The callback URLs and headers are API key-specific.

One possible use for additional headers is checking the origin of a PUT request, as well as distinguishing the application (API key) to which the notification belongs.

Note: Only one callback URL for each API key can be active. If you register a new URL while another one is active, it replaces the active one. There can be only one notification channel at a time for each API key. If another type of channel is already present, you need to delete it before setting the callback URL.

Expiration of a callback URL:

A callback can expire when Device Management cannot deliver a notification due to a connection timeout or error response (4xx or 5xx). After each delivery failure, Device Management sets an exponential back-off time and makes a retry attempt after that. The first retry delay is 1 second, then 2s, 4s, 8s, up to a maximum delay of two minutes. The retry delay is applied when the response is received, or in case of timeout, after the timeout expires. The request timeout is 20 seconds; in the case of timeout, the first retry happens 20 + 1 seconds after the first delivery attempt, then 20 + 2 seconds, and so on. The callback URL is removed if all retries fail within 24 hours. More about notification sending logic in the Device Management documentation.

Supported callback URL protocols:

Currently, only HTTP and HTTPS protocols are supported.

HTTPS callback URLs:

When delivering a notification to an HTTPS-based callback URL, Device Management Connect identifies itself with a valid client certificate. The certificate is signed by a trusted certificate authority (GlobalSign), with a Common Name (CN) set to notifications.mbedcloud.com.

Configuration options:

The event notification channel provides configurations options defined in Serialization config.

Example:

This example command shows how to set your callback URL and API key. It also sets an optional header authorization. When Device Management Connect calls your callback URL, the call contains the authorization header with the defined value.

curl -X PUT https://api.us-east-1.mbedcloud.com/v2/notification/callback \
-H 'Authorization: Bearer <api_key>' \
-H 'content-type: application/json' \
-d '{
  "url": "{callback-url}",
  "headers": {"authorization": "f4b93d6e-4652-4874-82e4-41a3ced0cd56"},
  "serialization": {"type": "v2", "max_chunk_size": "100",
    "cfg": {"deregistrations_as_object": "true", "include_uid": "true", "include_timestamp": "true", "include_original_ep": "true"
    }
  }
}'
Consumes
This API call consumes the following media types via the Content-Type request header:
  • application/json
Request body
webhook Webhook (required)
Body Parameter — A JSON object that contains the optional headers and URL where notifications are sent.
Responses
status description schema
204 Successfully subscribed.
400 Given URL is not accessible, or other type of channel already exists.
401 Unauthorized.
403 Forbidden. The authorization token used is not an API key.
415 Unsupported Media Type.
put /v2/notification/websocket
Register a websocket channel. Show more Show less

Register (or update) a channel using websocket connection to deliver notifications. The websocket channel should be opened by client using /v2/notification/websocket-connect endpoint. To get notifications pushed, you must place subscriptions. For more information on notification messages, see NotificationMessage.

A websocket channel can have only one active websocket connection at a time. If a websocket connection for a channel exists and a new connection to the same channel is made, the connection is accepted and the older connection is closed.

Note: Only one websocket channel for each API key can be active at a time. If you register a new websocket channel while another one is active, it replaces the previously active one. If another type of channel is already present, you need to delete it before registering a websocket channel.

Expiration of a websocket:

A websocket channel is expired if the channel does not have an opened websocket connection for a 24-hour period. Channel expiration means the channel is deleted and any undelivered notifications stored in its internal queue is removed. As long as the channel has an opened websocket connection or time between successive websocket connections is less than 24 hours, the channel is considered active, notifications are stored in its internal queue and delivered when a websocket connection is active. A channel can be also deleted explicitly with a DELETE call.

More about notification sending logic.

Configuration options:

The event notification channel provides configurations options defined in Serialization config

Example:

curl -X PUT https://api.us-east-1.mbedcloud.com/v2/notification/websocket \
-H 'Authorization: Bearer <api_key>'
-d '{
  "serialization": {"type": "v2", "max_chunk_size": "100",
    "cfg": {"deregistrations_as_object": "true", "include_uid": "true", "include_timestamp": "true", "include_original_ep": "true"
    }
  }
}
Consumes
This API call consumes the following media types via the Content-Type request header:
  • application/json
Return type
Example data
Content-Type: application/json
{
  "serialization" : "{}"
}
Responses
status description schema
200 Channel successfully updated. In the current v2 implementation this operation has no effect, and any subsequent PUT call from a client previously registered to a channel results in a 200 OK response. RegisterWebsocketChannel
201 Channel succesfully registered. WebsocketChannel
400 Other type of channel already exists.
401 Unauthorized.
403 Forbidden. The authorization token used is not an API key.

Models

AsyncIDResponse

id (optional)
String

The unique ID of the asynchronous response.

status (optional)
Integer

States whether sending a command to the device succeeded or failed.

Code Description
200 Operation succeeded. The payload contains result of the operation from the device.
400 The device rejected the request, possibly because it does not support the request method. See how the supported methods are [configured for the device resources](../device-management/collecting-resources.html#setting-the-operation-mode).
404 The device replied that it does not have the requested resource.
412 Precondition failed and the operation was not executed. The device responded with 4.12 CoAP response code. The device may reject a subscription request with this response code.
413 Request entity is too large and could not be delivered to the device.
415 The device does not support the media type in the request.
429 An expired request was removed from queue (REQUEST_EXPIRED), the device requested deregistration (DEVICE_REMOVED_REGISTRATION), or the device was suspended (DEVICE_BLOCKED). The request was never delivered to the device.
502 The request to the device failed and the retry count was exceeded. The last retry failed to establish TCP or TLS connection to the device.
503 The request to the device failed and the retry count was exceeded. The last retry failed, because the device is currently unavailable (NOT_CONNECTED).
504 The request to the device failed and the retry count was exceeded. The last retry failed, because the device did not respond in time according to the protocol-specific retransmission logic (TIMEOUT).

error (optional)
String

An optional error message describing the error. Please refer to status listing above.

payload (optional)
String

Requested data, base64 encoded.

ct (optional)
String

The content type.

max-age (optional)
String

Determines how long this value stays valid in the cache, in seconds. 0 means that the value is not stored in the cache.

ChannelMetadata

delivery_mechanism (optional)
String

Channel delivery mechanism.

Enum:
CALLBACK
LONG_POLLING
WEB_SOCKET

EndpointData

ep (optional)
String

Unique Device Management device ID.

original-ep (optional)
String

If device registration is initiated with a self-provided endpoint name, Device Management provides a new device ID for subsequent use. The new platform-provided Device ID is forwarded as the 'ep' property and the original self-provided one as the optional 'original-ep' property in a registration notification. The name and ID can then be mapped accordingly. Device Management saves the original endpoint name in the Device Directory for future device registrations so you don't need to do mapping again.

ept (optional)
String

Endpoint type.

q (optional)
Boolean

Queue mode (default value is false).

resources (optional)

NotificationData

ep (optional)
String

Device Management Device ID.

path (optional)
String

URI path.

ct (optional)
String

Content type.

payload (optional)
String

Base64 encoded payload.

max-age (optional)
String

Max age value is an integer number of seconds between 0 and 2^32-1, but the actual maximum cache time is limited to 3 days. Default 60.

NotificationMessage

notifications (optional)
registrations (optional)
reg-updates (optional)
de-registrations (optional)
registrations-expired (optional)
async-responses (optional)

RegisterWebsocketChannel

serialization (optional)
Object

Serialization configuration for a channel

ResourcesData

path (optional)
String

Resource's URI path.

if (optional)
String

Interface description that defines a name or URI that indicates how to interact with the target resource. It describes a generic interface type, such as a 'sensor'.

rt (optional)
String

Application-specific resource type that describes this resource. It is created by the client side application. Not meant to be a human-readable name for the resource. Multiple resource types may be included, separated by a space.

ct (optional)
String

Content type.

obs (optional)
Boolean

Whether the resource is observable (true/false).

SerializationConfigData

type
String

Serialization type: v2 - specified in NotificationMessage.

Enum:
v2
max_chunk_size (optional)
Integer

Maximum number of messages in NotificationMessage container delivered in one request. Default is 10000. Using a very low value for high troughput applications may cause lag in notification delivery, as a new chunk is sent only after the previous one has been acknowledged. Using a high value is recommended and safe, as chunks are sent quickly after notifications are received from devices. See notification sending logic for more details.

cfg (optional)
Object

Serialization configuration object according to configuration type.

SerializationConfigObjectV2

deregistrations_as_object (optional)
Boolean

Defines serialization format for 'de-registrations' and 'registrations-expired'. If set to true, de-registration and registration-expired messages will be represented as json objects and can have additional fields: 'uid', 'timestamp', 'original-ep', together with the 'ep' field. If set to false, (default) - de-registration and 'registration-expired' will be represented by a string, containing only data from 'ep' field.

include_uid (optional)
Boolean

Include 'uid' message field to serialized objects. This is message ID, and can be used for duplicate detection.

include_timestamp (optional)
Boolean

Include 'timestamp' message field in serialized objects. The timestamp represents the time that the notification service receives the message and sorts it into the queue. Timestamp provides information of queue length (web-app current time - timestamp = delay).

include_original_ep (optional)
Boolean

Include 'original-ep' message field in serialized objects. This is the endpoint_name from the device.

Webhook

url
String

The URL to which the notifications are sent. We recommend that you serve this URL over HTTPS.

headers (optional)
map[String, String]

The headers (key/value) sent with the notification. Optional.

serialization (optional)
Object

Serialization configuration for a channel.

WebsocketChannel

status (optional)
String

Channel status is 'connected' when the channel has an active WebSocket bound to it. The status is 'disconnected' when either the channel or the WebSocket bound to it is closed and 'unknown' when the server cannot determine it.

Enum:
connected
disconnected
unknown
queue_size (optional)
Integer

Number of events in the channel's event queue waiting to be delivered. If the server cannot determine the queue size the value will be set to -1.

serialization (optional)
Object

Serialization configuration for a channel.