Using the nRF Cloud Message Routing Service

This guide explains how to use the nRF Cloud Message Routing Service through the nRF Cloud portal and APIs.

Prerequisites

• Create an nRF Cloud account.
• Have an Owner or Admin role in your team.
• Create a destination with your web service URL. For more information and an example, see Receiving messages from nRF Cloud.
• Verify your destination. Before your server can start receiving messages from your team, it must be verified. See Verification for details.
• Add one or more devices to your team.

Using the nRF Cloud portal

This section explains message routing operations available in the nRF Cloud portal.

Managing destinations

You can create, edit, delete, test, enable or disable, and verify destinations in the nRF Cloud portal.

Creating

After you have an HTTP server that can receive requests from nRF Cloud, finish setting up message routing by creating a new destination:

1. Log in to the nRF Cloud portal.

2. Select Device Management from the left sidebar.

   A panel opens to the right.

3. Select Message Routing Service.

4. Click the Add Destination button.

   A pop-up opens.

5. Enter the name of the destination and URL.

6. (Optional) Enter additional information:

   • Contact email address: You need this if you want to receive email alerts when your DLQ has more than 20 messages in it.
   • Filter Categories: Configure message filtering to control which types of messages are forwarded to your destination. See Message Filtering for details.
   • Token: Provide this if your own service requires it, or as a convenient way to identify messages from nRF Cloud. Adds x-api-key to requests with your token value.
   • Secret: Used for identity verification. Adds x-nrfcloud-signature to requests.
   • Verify Server Socket Layer toggle: Leave this as-is, unless you want to disable SSL.
   • Is Enabled toggle: Leave this on if you want the destination to be enabled on creation.

7. Click the Create Destination button.

Editing

To edit an existing destination:

1. Log in to the nRF Cloud portal.

2. Select Device Management from the left sidebar.

   A panel opens to the right.

3. Select Message Routing Service.

4. Click the name of the destination you want to edit.

5. Click the pencil icon.

   A pop-up opens.

6. Edit the destination as needed. You can also add a notification email address if you did not add one when you created the webhook.

7. Click Save Destination.

Enabling and disabling

To enable or disable a destination:

1. Log in to the nRF Cloud portal.

2. Select Device Management from the left sidebar.

   A panel opens to the right.

3. Select Message Routing Service.

4. Click the name of the destination you want to enable or disable.

5. Click the Destination is enabled toggle on or off as needed.

   You can also click the Is Enabled toggle while editing the destination to enable or disable it.

Testing

To test the message delivery to a destination, send a test message through the nRF Cloud portal.

1. Log in to the nRF Cloud portal.

2. Select Device Management from the left sidebar.

   A panel opens to the right.

3. Select Message Routing Service.

4. Find your destination in the list of destinations, and click the icon in the Test column. Alternatively, click the name of the destination you want to test, then click the same icon in the upper right of the page.

   A notification indicates whether the test was successful.

Verifying

To verify your destination:

1. Log in to the nRF Cloud portal.

2. Select Device Management from the left sidebar.

   A panel opens to the right.

3. Select Message Routing Service.

4. Click the name of the destination you want to test.

5. Click the Verify Destination button. No message is sent to your destination at this time.

6. The first verification message is sent by nRF Cloud through HTTP POST when you create the destination or update the URL of the destination. Find the 6-digit token value in the message your destination received at that time. If the message is not obtainable, click the Resend Code link and wait for your destination to receive the verification token.

7. Enter the verification token and click Verify URL.

In the list of destinations page, the Verified column shows a yellow UNVERIFIED badge or a green VERIFIED badge for each destination. In a destination's detail page, the badge is in the upper right of the page.

Using the nRF Cloud APIs

This section explains message routing operations through the nRF Cloud APIs.

Managing destinations

See the Message Routing Service API documentation for more information on specific endpoint requirements.

Creating

Call the CreateDestination endpoint to create a new destination.

Example request body:

{
    "name": "Test Webhook",
    "config": {
        "type": "http",
        "url": "https://example.com/webhook-endpoint",
        "verifySsl": true
    },
    "dlqNotificationEmails": [
        "user1@example.com",
        "user2@example.com",
    ],
    "isEnabled": true
}

The server responds with HTTP 201 and information about the newly created destination:

{
    "id": "5b5d8b40-e251-41bc-a45c-f932c603f121",
    "createdAt": "2024-08-07T03:38:15.040913Z",
    "name": "Test Webhook",
    "config": {
        "type": "http",
        "url": "https://example.com/webhook-endpoint",
        "verifySsl": true
    },
    "isEnabled": true,
    "errors": [],
    "dlqSize": 0,
    "dlqNotificationEmails": ["user1@example.com","user2@example.com"]
}

Viewing

To view your destinations, call the ListDestinations endpoint.

The server responds with a list of your destinations:

{
    "items": [
        {
            "id": "f7de2039-06bd-4da5-b493-7ed0a038ccf3",
            "name": "Test Destination 01",
            "config": {
                "type": "http",
                "url": "http://example.com/endpoint",
                "verifySsl": false
            },
            "isEnabled": true,
            "errors": [
                {
                    "correlationId": "01200898-6213-49b6-a97b-2c8eb6209367",
                    "createdAt": "2024-09-13T20:10:45.497247Z",
                    "reason": {
                        "message": "Received non 2xx response from webhook destination",
                        "response": {
                            "body": {
                                "message": "INTERNAL_SERVER_ERROR"
                            },
                            "status": 500
                        }
                    }
                },
                {
                    "correlationId": "debcbcbe-3f6b-404f-b3ea-9f8d0a66854f",
                    "createdAt": "2024-09-13T20:10:38.810562Z",
                    "reason": {
                        "message": "Received non 2xx response from webhook destination",
                        "response": {
                            "body": {
                            "message": "INTERNAL_SERVER_ERROR"
                        },
                        "status": 500
                    }
                }
            ],
            "dlqSize": 4,
            "dlqNotificationEmails": [
                "user@example.com"
            ],
            "createdAt": "2024-09-19 00:00:17.867+00",
            "verified": false
        }
    ],
    "total": 1,
    "pageNextToken": "def456"
}

Editing

Call the UpdateDestination endpoint to edit an existing destination.

Example request body:

{
    "name": "Warehouse 2",
    "dlqNotificationEmails": [
        "alerts@example.com"
    ],
    "config": {
        "url": "https://example.com/webhook-endpoint/warehouse2"
    }
}

The server responds with HTTP 200 and confirmation that the destination information has changed:

{
    "id": "fad832da-c249-4c06-a60a-d604540ac76e",
    "createdAt": "2024-09-13T20:13:07.920601Z",
    "name": "Warehouse 2",
    "config": {
        "type": "http",
        "url": "https://example.com/webhook-endpoint/warehouse2",
        "verifySsl": true
    },
    "isEnabled": true,
    "errors": [],
    "dlqSize": 0,
    "dlqNotificationEmails": [
        "alerts@example.com"
    ]
}

Enabling and disabling

Call the UpdateDestination endpoint and set isEnabled to true to enable a destination.

Example request body:

{
    "isEnabled": true,
}

Call the UpdateDestination endpoint and set isEnabled to false to disable a destination.

Example request body:

{
   "isEnabled": false,
}

Deleting

Call the DeleteDestination endpoint to delete a destination. Include the destination ID.

The server responds with HTTP 204.

Caution

Deleting a destination also permanently deletes any messages in the DLQ for that destination.

Testing

Call the TestDestination endpoint to test your webhook. Include the destination ID.

The server responds with HTTP 200.

Example response:

{
  "destination_response": {
    "status": 200,
    "body": {
        "type": "test",
        "messages": [
        {
            "teamId": "8da943d3-f0f0-432d-a662-20bfdc0f3145",
            "messageId": "161159c9-a1dd-4519-9f38-a02307191729",
            "receivedAt": "1739842247513",
            "topic": "#",
            "message": {
                "event": "Test Message from nRF Cloud"
            }
        }
        ],
        "timestamp": "2025-02-18T01:30:47.513Z"
    },
    "headers": {
      "content-type": "application/json"
      "x-nrfcloud-team-id": "8da943d3-f0f0-432d-a662-20bfdc0f3145"
    }
  }
}

Sending a verification token

Call the SendVerification endpoint to send a verification token to your webhook.

The server responds with HTTP 204.

Verifying a destination

Call the VerifyDestination endpoint with the verification token value sent by nRF Cloud to your destination.

Example request body:

{
  "verificationToken": "012345"
}

The server responds with HTTP 204.

Message filtering

You can optionally configure message filtering for your destinations to control which types of messages are forwarded to your destination.

Pre-defined 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

Configuring message filters

You can configure message filtering through both the nRF Cloud portal and the APIs.

Through the nRF Cloud portal

When creating or editing a destination in the portal:

1. In the destination configuration form, locate the Filter Categories field.
2. Select the categories you want to forward to this destination.
3. Only messages matching the selected categories will be sent to your endpoint.
4. If no filters are specified, all message types will be forwarded (default behavior).

Through the APIs

When using the CreateDestination or UpdateDestination endpoint, include a filter object in your destination configuration:

{
  "name": "My Filtered Destination",
  "config": {
    "type": "http",
    "url": "https://example.com/webhook",
    "verifySsl": true
  },
  "filter": {
    "categories": ["location", "shadow"]
  },
  "isEnabled": true
}

Examples

• To receive only location and shadow messages: ["location", "shadow"]
• To receive only device messages: ["device_messages"]
• To receive all messages (default), clear the filter object.

Using the 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 ListDLQItems endpoint.

nRF Cloud checks the DLQ once a day. If the DLQ 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.

Viewing and managing the DLQ through the APIs

This section explains how to view and clear the DLQ.

Viewing

Call the ListDlqItems endpoint to view messages in the DLQ.

The server responds with HTTP 200 and a list of messages in the DLQ.

Example response:

{
    "items": [
        {
            "teamId": "a5592ec1-18ae-4d9d-bc44-1d9bd927bbe9",
            "destinationId": "a5592ec1-18ae-4d9d-bc44-1d9bd927bbe9",
            "deviceId": "string",
            "messageId": "a5592ec1-18ae-4d9d-bc44-1d9bd927bbe9",
            "topic": "string",
            "message": {
                "temperature": 25
            },
            "receivedAt": 0,
            "createdAt": 0
        }
    ],
    "total": 10,
    "pageNextToken": "4bb1f9ab35bd"
}

Clearing

Call the FlushDlqItems endpoint to manually clear all messages from the DLQ.

Caution

Clearing the DLQ permanently deletes the messages in it.

The server responds with HTTP 204.

When you delete a destination, the DLQ is also cleared.