How to integrate with Hubble

General Tutorials
1

This tutorial provides a step-by-step guide to integrate the Hubble Network with the TagoIO platform. By following these instructions, every packet your Hubble devices broadcast (payload, gateway location and gateway details) will be forwarded to TagoIO, where you can decode, store and visualize it.

Hubble is uplink only: the network forwards what your devices transmit, and there is no downlink path to send commands back to them.

Prerequisites

  • TagoIO account: sign up at admin.tago.io/signup if you do not have one.
  • Hubble account: an organization in the Hubble Dashboard, Sandbox or Live, with at least one registered device that is transmitting.

Step 1: Create Authorization in TagoIO

  1. Access the Authorizations page
    • In TagoIO Admin, go to Devices > Authorizations.
    • Learn more: Authorization.
  2. Create a new authorization
    • Click Create Authorization, give it a meaningful name such as Hubble-Integration, and save.
  3. Copy the authorization token
    • You will paste it into the Hubble webhook URL in the next step.

:information_source: Note: One Authorization is enough for all Hubble devices of the same organization. Create another one only for a separate integration or a separate TagoIO profile.

Step 2: Create the webhook in Hubble

Hubble delivers packets to HTTPS endpoint per organization. The TagoIO middleware is that endpoint, and the Authorization from Step 1 travels in the URL.

  1. In the Hubble Dashboard, go to Webhooks and click + Create webhook.

  2. Fill in the form:

    Field Value
    Webhook Name TagoIO
    Target URL https://hubble.middleware.us-e1.tago.io/uplink?authorization=YOUR_AUTHORIZATION
    Max Batch Size 100

    Replace YOUR_AUTHORIZATION with the token from Step 1. If your TagoIO account is in the European region, use hubble.middleware.eu-w1.tago.io instead of us-e1.

  3. Click Create webhook.

Screenshot 2026-09-21 at 08.51.11
Screenshot 2026-09-21 at 08.51.111440×966 125 KB

:information_source: Note: Keep Max Batch Size at 100. Hubble sends packets periodically or as soon as the batch reaches this size, and 100 is the value this integration is designed for. Batches above 1,000 packets are rejected.

:information_source: Note: After creation, Hubble shows a webhook secret. This integration does not use it: the Authorization in the URL is what authenticates each delivery. You can close the dialog without saving the secret.

Using TagoDeploy?

If you run a TagoDeploy instance with its own Hubble middleware, point the Target URL at your own domain:

https://<your-hubble-middleware-domain>/uplink?authorization=YOUR_AUTHORIZATION

Step 3: Add Your Device to TagoIO

  1. Copy the Device ID from Hubble
    • In the Hubble Dashboard, open Devices and copy the Device ID of your device.
  2. Create the device in TagoIO
    • In TagoIO Admin, go to Devices > New Device and search for Hubble.
    • Pick the connector for your device model if it is listed, or Custom Hubble for any other device.
  3. Fill in the device form
    • Enter a Device Name.
    • Paste the Hubble Device ID into the ID field. It must match exactly: TagoIO uses it to route each packet to this device.
    • Click Create my Device.

For detailed instructions, see Adding Devices.

Screenshot 2026-09-21 at 08.46.51
Screenshot 2026-09-21 at 08.46.511366×1156 151 KB

:information_source: Note: Packets for a Device ID that has no device in your profile are not stored. Create the device before its first transmission, and compare the UUID character by character when data does not show up where you expect.

Finalizing Setup

  1. Wait for the first packets

    • Power on your device or wait for its next transmission. Hubble delivers packets in batches, periodically or as soon as 100 packets accumulate.

  2. Verify data reception

    • In TagoIO Admin, open your device and check the Data tab, or use the Live Inspector to watch packets arrive in real time.
    • The Hubble network parser expands each packet into these variables:
    Variable Content
    payload The bytes your device transmitted, as a hex string. Hubble delivers them in Base64 and the network parser converts them
    gateway_location Latitude and longitude of the gateway fix, with altitude, horizontal_accuracy, vertical_accuracy and network_type (TERRESTRIAL or SATELLITE) in the metadata
    gateway_id, gateway_service_id The gateway that heard the device, when Hubble reports it

    The packet as Hubble sent it is not stored as a variable. Fields the table leaves out, such as the device name, rssi, counter, sequence_number and the device tags, are still in the request: read them from raw_payload in your payload parser if you need them. See Context & Global Variables.

  3. Decode your payload

    • payload holds the hex of what your firmware broadcasts, and only you know its layout. Decode it in the device’s payload parser, which runs after the network parser.

Troubleshooting

Error 401 - Unauthorized

  • Missing authorization: the message is invalid or missing authorization. The webhook URL has no ?authorization= parameter, or its value is not the 34-character token from Step 1. Check the Target URL in Hubble.
  • Invalid Authorization token: the message is authorization refused by TagoIO: Token can't be found. The token in the URL does not exist in your TagoIO profile. Compare it with Devices > Authorizations.
  • Wrong region: a token from a European account is refused on us-e1, and the other way around. Match the URL region to your TagoIO account.

Error 400 - Bad Request

  • Batch too large: Max Batch Size is above 1,000. Set it back to 100.
  • Unexpected body: something between Hubble and TagoIO changed the request body. Point the webhook straight at the middleware URL.

200 with failed above zero

  • The middleware answers each batch with { "status": true, "result": { "received", "sent", "invalid", "failed" } }. A failed count means TagoIO refused or did not answer for at least one device in that batch; those packets were not stored. Hubble does not resend a batch answered with 200, so check the affected device in the Live Inspector and wait for the next transmission.

No Data Received

  • Device ID mismatch: compare the ID field in TagoIO with the Device ID in the Hubble Dashboard. They must be identical; a packet whose ID matches no device is dropped.
  • Webhook on another organization: a webhook belongs to one Hubble organization. Make sure it was created in the organization where the device is registered (Sandbox and Live are separate).
  • Webhook in retry: after an error response, Hubble retries with increasing delays for up to 3 hours. Open Webhooks in the Hubble Dashboard to see the delivery status and the last error.
  • Check the Live Inspector: open it before the next transmission to confirm whether packets reach TagoIO at all.

With data flowing into TagoIO, you can start creating Dashboards, Analyses, and Actions to visualize and manage your device data.

1 Like