Message Routing Service

The nRF Cloud Message Routing Service allows you to forward device messages from nRF Cloud to another destination, such as your own web service.

Messages that fail delivery on the first try are added to a retry queue. The service will automatically retry delivery for 24 hours. If a message cannot be delivered after 24 hours of retries, it is moved to the Dead Letter Queue.

You must provide a destination URL for your HTTP server. You can enable and disable the destination as needed and provide a contact email address for notifications. You can manage your destinations through the nRF Cloud portal or APIs.

Plan and role requirements

The service is available for all plan types:

• Developer teams can use one destination for free.
• Pro and Enterprise teams are not limited. The service is billed by delivered device message to a single destination. A message delivered to multiple destinations is billed by each delivery to each destination.

Access

Destination management is available only to Admin and Owner roles. These actions affect the entire team: since Editors might not have access to all devices on a team, they cannot manage destinations.

Viewers are able to see destinations, and Editors can send test messages.

Security

SSL verification is standard for payload delivery unless you disable it using the verifySsl property in your destination configuration when you create the destination.

Authentication

nRF Cloud provides two ways to verify the authenticity of incoming requests: by API key or by signature. You can choose either or both methods when you create or update your destination.

API key authentication

When you create a new destination, one of the parameters you can provide to nRF Cloud is a plain-text string that will be included in all messages sent to your destination in every request's x-api-key header.

Signature authentication

When you create a new destination, one of the parameters you can provide to nRF Cloud is a secret string that is used to generate the x-nrfcloud-signature header. The header value is an HMAC hex digest of the request payload, hashed using your provided secret. The secret is never revealed in responses from the nRF Cloud server. Your destination creates its own HMAC digest with the same secret and verifies that it matches the header value in the request. Employ constant-time string comparisons to mitigate timing attacks.

Verification

Your destination does not receive messages until it is verified. This is to ensure that the destination is correctly configured and can receive messages. There are two ways to verify a destination: automatic verification or two-step verification. Once your destination is verified, nRF Cloud begins to send messages to your destination.

Automatic verification

nRF Cloud initially sends a verification message through POST to the specified URL when you create the destination. If your destination responds with a 2XX status code with a response header x-team-id that matches your team ID, the destination is automatically verified.

Two-step verification

Two-step verification is a process in which:

1. nRF Cloud sends a verification token as a 6-digit number to your destination in a message.

2. You find the verification token number in the message your destination received, and provide it to nRF Cloud.

If the number you provide does not match the number sent by nRF Cloud, the destination remains unverified, and you need to request a new verification token from nRF Cloud. The original number becomes invalid and cannot verify your destination.

The first verification message is sent by nRF Cloud when you create the destination or update the URL of the destination.

You can verify your destination using the nrfcloud.com portal or using the REST API.

Testing

You can test your destination through the nRF Cloud portal. Verification is not required before testing your destination. When you test your destination, nRF Cloud sends a test messages using POST to the specified URL.

Supported messages

See MQTT topics for more information on supported message types.

Message order is not guaranteed. To determine the message order, see the message timestamp. When nRF Cloud sends a message to your destination endpoint, it sends a JSON payload with specific fields.

Example

{
  "type": "device.messages",
  "timestamp": "2024-09-05T21:59:47.323Z",
  "messages": [
    {
      "teamId": "26fc871f-1272-45ef-9db2-0145a6b0dfcd",
      "deviceId": "nrf-278345628733",
      "messageId": "9b66d97e-9747-4690-a464-073748736603",
      "receivedAt": "2024-09-05T21:59:44.714Z",
      "topic": "dev/26fc871f-1272-45ef-9db2-0145a6b0dfcd/m/d/nrf-278345628733/d2c",
      "message": {
        "appId": "TEMP",
        "messageType": "DATA",
        "data": "14"
      }
    },
    {
      "teamId": "26fc871f-1272-45ef-9db2-0145a6b0dfcd",
      "deviceId": "nrf-278345628733",
      "messageId": "23f5bbc1-2dd8-455e-962a-cad780d469f9",
      "receivedAt": "2024-09-05T21:59:45.306Z",
      "topic": "dev/26fc871f-1272-45ef-9db2-0145a6b0dfcd/m/d/nrf-278345628733/d2c",
      "message": {
        "appId": "GPS",
        "messageType": "DATA",
        "data": "$GPGGA,195032.465,4531.255,N,12240.318,W,1,12,1.0,0.0,M,0.0,M,,*79"
      }
    }
  ]
}

Payload fields

The payload consists of the following fields:

• type: The type of the message batch. For device messages, this is device.messages. Other types include test for test messages and system.verification for verification messages.
• timestamp: The time when the batch was sent, in ISO 8601 format.
• messages: An array of message objects. Each message object contains the following information:
  • teamId: A unique identifier of your team in nRF Cloud.
  • deviceId: A unique identifier of the device that sent the message.
  • messageId: A unique identifier for the individual message.
  • receivedAt: The time when the message was received by nRF Cloud, in ISO 8601 format.
  • topic: The MQTT topic associated with the message, indicating the path used in communication.
  • message: An object containing the actual message data sent.

Message filtering

Message filtering allows you to control what kind of messages are forwarded to your destination by selecting from pre-defined categories. Without filtering, all messages are delivered. With filtering enabled, only messages from your selected categories are sent to your destination.

Filtering categories

The following pre-defined filtering categories are available:

• location: Location-related messages (AGNSS, AGPS, PGPS, Ground fix, Cell positioning, Wi-Fi positioning)
• shadow: Device shadow messages (shadow updates, state changes)
• fota: Firmware over-the-air update messages
• device_messages: Device-to-Cloud messages (including binary and raw data)
• cloud_messages: Cloud-to-Device messages

Usage

You can configure the filtering when creating or updating a destination as follows:

• Select multiple categories for one destination.
• Use different filters for different destinations.
• Change filters without recreating destinations.

For configuration details and examples, see Message Filtering.

Dead letter queue

If a message cannot be routed to its destination, delivery will be retried for up to 24 hours. If the message still cannot be delivered after this period, it will be moved to the dead letter queue (DLQ).

To view the failed messages in the DLQ, you can use the portal or the ListDLQItems endpoint.

nRF Cloud checks the DLQ once a day. If it contains more than 20 failed messages at the time of the check, a notification email is sent to the DLQ notification email address for that destination, if you have provided one.

Messages remain in the DLQ for up to 30 days, after which they are deleted automatically. You can also manually clear the DLQ at any time.

Next steps

See the guides to message routing operations and creating an HTTP server to handle messages.