Message Routing

The Message Routing Service forwards messages to your own services as they arrive, so you do not have to poll nRF Cloud for new data. Each destination is an HTTP endpoint of yours that nRF Cloud POSTs messages to, and you choose which categories of message it receives.

The Message Routing page in the web app, under Data Ingestion, lists your destinations and is where you create and manage them.

Access

Managing destinations requires the Organization Admin role. See Organization Admin.

A Developer-plan organization can have one destination. Organizations on a Pro plan or above can have up to 100 destinations.

Destinations are shared across your organization and are managed from its default project. In any other project, the menu item is disabled.

Creating a destination

Before you start, you need a publicly reachable HTTP endpoint that accepts POST requests and answers with a 2XX status code. HTTPS with a valid certificate is recommended. If you do not have an endpoint yet, see Message Routing Service quickstart, which walks through prototyping with a request bin and then handling the payloads for real.

To create a destination:

1. Go to Data Ingestion → Message Routing and click Create Destination.

2. Enter a Name. Names must be unique within the organization.

3. Enter the URL that messages are delivered to.

4. (Optional) Add Notification Emails. These addresses are notified when deliveries to this destination keep failing. See When delivery fails.

5. (Optional) Select Data Categories to receive only some of your traffic:

   • Location — location-related messages, including AGNSS, AGPS, PGPS, ground fix, cell positioning, and Wi-Fi positioning
   • Shadow — device shadow messages, including shadow updates and state changes
   • Legacy FOTA — firmware over-the-air update messages from the legacy nRF Cloud experience; this category does not include messages from Memfault's OTA engine in the new nRF Cloud experience
   • Device Messages — device-to-cloud messages, including binary and raw data
   • Legacy Cloud Messages — cloud-to-device messages published through legacy nRF Cloud MQTT topics, excluding Location Services messages

   Leave this empty to route every category. Filtering here means you are not billed for deliveries you would discard on arrival.

6. (Optional) Open Advanced Settings to configure how deliveries are authenticated:

   • Token — sent as the x-api-key request header. Provide this if your service requires it, or as a convenient way to recognize requests from nRF Cloud.
   • Secret — used to sign each delivery. nRF Cloud sends an HMAC digest of the payload in the x-nrfcloud-signature header, which your service can recompute with the same secret. The secret is not displayed after you save it.
   • Require valid SSL certificate — on by default. Turn it off only if your endpoint presents a certificate nRF Cloud cannot validate.

   To authenticate a delivery, compare x-api-key with the configured token, or calculate an HMAC-SHA256 digest of the raw request body using the configured secret and compare its lowercase hexadecimal value with x-nrfcloud-signature. Use a constant-time comparison for secrets and signatures.

   note

   Once set, a token or a secret can be changed but not removed. Leaving either field empty when editing keeps the stored value. To drop one entirely, recreate the destination.

7. Leave Enable this destination on, unless you want to configure it now and start delivery later.

8. Click Create and Verify.

The verification dialog opens, and the new destination appears in the list as Unverified. Nothing is delivered to it until it is verified.

Verifying a destination

Verification proves that the URL you entered is an endpoint you control. nRF Cloud POSTs a verification message to the destination as soon as you create it, and again whenever you change its URL.

There are two ways it can complete.

Automatic verification

If your endpoint answers that verification request with a 2XX status code and echoes the x-nrfcloud-team-id header it received, the destination is verified immediately. Nothing further is needed and no PIN is involved.

Verifying with a PIN

Otherwise, the verification message carries a 6-digit PIN, which you read from the request your endpoint received:

{
  "type": "system.verification",
  "messages": [{ "verificationToken": "171507" }],
  "timestamp": "2026-07-30T15:51:58.222304705Z"
}

To finish verification:

1. Find the destination in the list and click Verify in the Verification Status column.
2. Enter the 6-digit PIN your endpoint received.
3. Click Confirm.

A PIN expires an hour after it is sent. If you no longer have it, click Resend to send a new one — this replaces the stored PIN, so any earlier one stops working. A wrong PIN is also discarded on entry, so resend after a rejected attempt rather than retyping.

If the resend cannot reach your destination, the dialog reports why and no PIN arrives; see When delivery fails for the causes. A resend can also complete verification outright, if your endpoint echoes the team ID header this time.

Sending a test message

Send test in the Test Message column or on the destination's detail page delivers a single test payload and reports what your endpoint did with it:

{
  "type": "test",
  "messages": [{ "event": "Test Message from nRF Cloud" }],
  "timestamp": "2026-07-30T15:51:58.222Z"
}

Testing works on destinations that are disabled or unverified, which makes it a good way to check an endpoint before you turn it on. Only one test runs at a time for the whole organization; if you test again too quickly the request is rate limited.

A test reports success only when your endpoint answered with a 2XX status code. Any other status is reported as a failure, along with the status itself.

Viewing destination details

Click a destination's name to open its detail page. The page summarizes its URL, verification and enabled status, data categories, notification emails, and SSL certificate setting. You can also edit, test, verify, or delete the destination from this page.

The Estimated Messages Sent (24h) card shows recent delivery volume, broken down by data category. Use it to identify a destination or category that has unexpectedly gone quiet; the values are estimates rather than billing records.

The Recent Forwarding Errors card shows up to five of the most recent errors from the last 30 days. Expand an error to inspect and copy the response returned by your endpoint.

Editing, disabling, and deleting

Use the pencil and trash icons in the destination list, or the Edit and Delete buttons on its detail page.

Changing the URL of a verified destination sends a fresh verification request to the new address, and delivery pauses until that destination is verified again. The form warns you before you save.

To stop delivery without losing the configuration, turn off Enable this destination. The Enabled column shows the current state for every destination.

Deleting a destination stops delivery. Messages still queued for retry are no longer delivered to it.

When delivery fails

A message that cannot be delivered is retried for up to 24 hours. If you configured Notification Emails, those addresses receive an alert when deliveries repeatedly fail.

When a verification or a test does not get through, the reason is reported in the web app:

Reported cause	What it means
The connection could not be established	The endpoint could not be reached at all — refused, reset, timed out, or at an address nRF Cloud will not connect to.
Its host name could not be resolved	DNS lookup for the host in the URL failed. Check the URL for typos.
The TLS handshake failed	The certificate could not be validated. Check it, or turn off Require valid SSL certificate.
It answered with a status	The endpoint was reached but answered with a non-2XX status code, which is shown.
No cause was reported	The delivery failed for a reason nRF Cloud cannot attribute to your endpoint. Try again.

Responses from your endpoint are never echoed back into the web app, so these causes are all you see here. To inspect a failing endpoint, read your own service logs.

Next steps

Continue with the Message Routing Service quickstart for a worked example of receiving and decoding messages end to end.