Get Device Packet Data

Start receiving packet data transmitted by your connected devices on Hubble Network.

---

How to Access Your Data

You can always view your packet data organized by device in your Dashboard.

For backend integration, Hubble provides two platform integration patterns for accessing your device packet data:

• Webhook Subscription: Register a target URL to have new packet data pushed to you via secure HTTP requests. Use webhooks when you need time-sensitive access to device data, for example to trigger downstream workflows or run system integrations.

• Packets API: Fetch the latest packets via API request, using a continuation token to ensure that no data is missed. Use the API to batch packet data updates in predictable intervals that you control. You may also retrieve historical data over a specific time period (such as for backfilling).

Both mechanisms for receiving packet data have advantages, and it is typical to use both for different aspects of your backend integration strategy:

Feature	Webhook subscription	Packets API request
Mechanism	Push: Hubble proactively sends data to your registered URL.	Pull: client actively requests data from Hubble Cloud.
Use Case	Near real-time needs, minimizing client-side polling, but requires a plan for potential downtime.	Guaranteed delivery, full control, backfilling supported, but potentially less time-sensitive data.
Timeliness	Near real-time: batched payloads pushed as new data becomes available.	Variable: client controls timing and frequency of requests.
Data Loss Risk	Depends on reliability and availability of the listener. If your listener is down beyond Hubble's retry window, must revert to API to backfill historic data.	Continuation tokens ensure no missed data. Clients can always reprocess historic data.
Integration	Provision a receiving endpoint and implement response code logic.	Logic required for API calls, pagination, error handling and retry.
Authentication	Verify POST request authenticity using webhook secret.	Same API token authentication as for device key provisioning.

---

Using Webhooks

Use webhooks to have all new packets pushed to your server as they arrive on our cloud. We do not filter data when sending webhooks: you will receive all new packets across all devices belonging to your organization, regardless of environment tag (Sandbox or Production).

Go further: Review Packet Webhook Example for the webhook request payload structure, for an array of data packets.

Set Max Batch Size

Configure the maximum number of packets that will be batched into a single webhook payload, up to 1,000 packets. When new packets are available, Hubble will send a webhook every several seconds or whenever this threshold is met - whichever occurs first.

Go further: Review Create a Webhook Endpoint for defining a target URL, setting batch size and giving your webhook a name.

Webhook Secret

When registering a new webhook, we provide a confidential, unique string that may be used to validate that the HTTP request comes from Hubble Network. Hubble will send this token in the HTTP header as HTTP-X-HUBBLE-TOKEN when attempting to post new data to your target URL.

Treat this token as a sensitive credential. Keep it strictly confidential to prevent unauthorized entities from sending forged webhook requests to your system.

Return Status Code

To ensure reliable delivery, please return a 2xx "success" HTTP status code (the very first line of the HTTP response) to acknowledge that your server has successfully received and processed the webhook event. For example, the status line might be HTTP/1.1 200 OK.

Any other response will be interpreted by Hubble as a "failure", which triggers our webhook retry logic (see below). We monitor webhook performance to protect system reliability, and we reserve the right to disable persistently failing webhooks after notice.

Retry Logic

Hubble maintains an "at least once" delivery system. If your server responds with a non-2xx status code when we attempt to post to the target URL we will automatically retry webhook requests using an exponential backoff strategy, for up to 3 hours. Because retries may cause duplicate deliveries, we recommend making your webhook handler idempotent to safely handle repeated events. Hubble expects a response within 10 seconds. If your processing takes longer, we might consider queuing the data and returning a 200 OK immediately.

If Hubble Network experiences temporary downtime, no data is lost. Webhook deliveries are queued and automatically resume from the last successfully sent packet, continuing until all queued packets are delivered and the system is up to date.

Total Webhooks

Hubble supports up to two (2) configured webhooks to facilitate integration cutover/migrations. Review our guidance on Migrating to a new webhook endpoint.

Webhook Security

Hubble operates on dynamic AWS infrastructure, meaning our outgoing IP addresses rotate frequently. We do not provide a fixed CIDR range for allowlisting.

To secure your endpoint, we maintain a two-layer security model based on encryption and authentication:

1. Transport Security (TLS): All webhooks are sent over encrypted HTTPS. This ensures your data—including the Hubble-provided webhook secret—cannot be intercepted in transit.
2. Webhook Secret: Every webhook POST request includes the confidential webhook secret associated with your target endpoint in the HTTP-X-HUBBLE-TOKEN header. This is used for message authentication.

---

Using Packets API

Pull the Packets API to get new packet data on a request schedule that you control.

Go further: Review Retrieve Organization Packets for example HTTP request, parameter definitions and response body.

Pagination

Packets are ordered by the timestamp given when they are ingested by Hubble Network. Up to 1,000 packets are returned per page.

A Continuation-Token will always be returned if there are more data packets to retrieve. Note that Hubble holds packets for a few seconds so that the Continuation-Token does not advance beyond packets that received an old processed timestamp due to clock drift.

Query by Timestamp

Use start and end time parameters to retrieve packet data over a specific time period. For example, if your webhook URL is unavailable beyond our retry interval, you may revert to the API to backfill device packet data.

Granular packet data is available up to 30 days in the past.

Request Data for a Single Device

Packet data may be filtered for a single device, for example for troubleshooting device behavior. This is not intended for high-volume data retrieval.

• Use the optional device_id parameter to request packet data for a specified device.
• Note that when a device ID is provided the endpoint will not behave as a continuous stream. If end is not provided, the endpoint will page until the current time then stop.

---

Parsing Packets

Hubble returns an array of up to 1,000 distinct data packets per API request (page size limit) or batched webhook (max batch size). Each packet object contains a packet.location and packet.device subobject with structured data, and packet.network indicating which layer of Hubble Network transmitted the data.

Go further: Review Retrieve Organization Packets for example HTTP request, parameter definitions and response body.

Device Object

• Device IDs: Use device.id—the Hubble UUID—to identify the device. (device.name may also be used as a proprietary device ID, but uniqueness is not enforced by Hubble. See Onboard Devices guide for more.)
• Timestamp: device.timestamp is the timestamp when the data packet was detected by the scanning gateway belonging to Hubble Network.
• RSSI: device.rssi is the received signal strength at the gateway (e.g. smartphone) from the Bluetooth® Low Energy (BLE) advertisement sent by your device. It is a one-sided measurement and does not automatically factor in Tx power from the device when reporting it (Tx power is not encoded in the advertising packet). RSSI value should be treated as a relative indicator, not an absolute distance metric.
• Custom Payload: Remember that device.payload is base64 encoded. As a best practice, we recommend double envelope encryption for the custom payload.

Location Object

• GPS: coordinates returned (lat/long and altitude) represent the location of the scanning gateway (e.g. a smartphone).
• Accuracy metrics: location.horizontal_accuracy and location.vertical_accuracy refer to the scanning gateway’s GPS fix at the time of reception. These values come directly from the scanning gateway's GPS chipset.
• Timestamp: location.timestamp is the timestamp from the scanning gateway's most recent GPS lock.

Review recommendations for how to Filter Packets based on these data fields in our implementation guide.