Data Delivery Overview

Sensos provides real-time, automated data delivery to stream periodic device reports, environmental sensor logs, and business-critical alerts directly into your enterprise infrastructure (TMS, ERP, IoT hubs, data lakes, and webhook receivers).

Rather than polling REST APIs continuously, Sensos pushes event payloads as they occur, providing low-latency visibility across your entire supply chain.

Supported Data Streams

Sensos supports four distinct event streams. You can configure independent delivery rules for any combination of streams:

1. Device Reports (Common Schema): Periodic status transmissions, movement detection, seal integrity, battery telemetry, and real-time cellular/GPS geolocation pings emitted by Sensos Smart Labels.
2. Temperature Logging: Sequential, timestamped temperature time-series logs recorded during transit for cold chain compliance and excursion analysis.
3. Humidity Logging: Sequential, timestamped relative humidity (%RH) logs recorded during transit for environmental monitoring.
4. Alerts: Event-driven notifications triggered when monitored conditions breach configured thresholds (e.g. temperature/humidity excursions, impact shocks, unauthorized stops, parcel tamper/light exposure, shipment arrival/departure, and flight landing).

Supported Destination Types

Sensos delivers data over HTTP: each event is sent as a single JSON request (Content-Type: application/json) to the URL configured in the rule, using the HTTP method you choose (Post, Put, or Get). Rules support static custom headers, OAuth2 or Basic authentication, an HMAC request signature, and automatic retries.

Configuring Data Delivery Rules via API

Data delivery rules are scoped to your Sensos operational account (accountId) and apply to all devices, shipments, and assets in that account. You can create and manage rules programmatically via the Sensos REST API. A new or changed rule takes effect within approximately 15 minutes.

Endpoint

POST https://api.sensos.io/v1/accounts/{accountId}/data-delivery-rules
Authorization: Bearer <TOKEN>
Content-Type: application/json

Delivery Rule Example

To configure a webhook receiver for device reports:

{
  "name": "Production TMS Webhook",
  "dataSourceType": "DeviceReport",
  "action": {
    "type": "Http",
    "method": "Post",
    "url": "https://api.yourcompany.com/webhooks/sensos",
    "headers": {
      "X-Webhook-Token": "<SHARED_SECRET_TOKEN>"
    }
  }
}

Request Fields

Authentication Options

Set action.authentication.type to one of the following:

OAuth2 — Sensos obtains an access token from your token endpoint and sends it as Authorization: Bearer <token>.

Basic — Sensos sends Authorization: Basic <base64(username:password)>.

{
  "name": "Alerts to ERP",
  "dataSourceType": "Alert",
  "action": {
    "type": "Http",
    "method": "Post",
    "url": "https://erp.yourcompany.com/sensos/alerts",
    "authentication": {
      "type": "OAuth2",
      "accessTokenUri": "https://login.yourcompany.com/oauth2/token",
      "grantType": "client_credentials",
      "tokenRequestContentType": "Form",
      "clientId": "<CLIENT_ID>",
      "clientSecret": "<CLIENT_SECRET>"
    }
  }
}

Request Signature

When action.signatureSettings is set, every request carries a signature header that lets you verify the request came from Sensos and the body was not modified.

The header value is the lowercase hexadecimal HMAC-SHA256 of the raw UTF-8 request body, keyed with secretKey. To verify, compute the same HMAC over the exact bytes you received (before parsing the JSON) and compare it to the header value using a constant-time comparison.

Reliability & Retry Semantics

Sensos delivers each event with an automated exponential backoff mechanism:

• One Request per Event: Every report, log, or alert is delivered as its own HTTP request.
• Expected Server Response: Your webhook receiver must respond with an HTTP 2xx status code (200 OK, 202 Accepted, or 204 No Content) within 10 seconds.
• Retry Triggers: Any non-2xx response (including 4xx), a timeout, a connection error, or a failure to obtain an OAuth2 access token causes the delivery to be retried.
• Retry Schedule: Failed deliveries are attempted up to 13 times (1 initial attempt + 12 retries) over approximately 34 hours. For the complete timing table, see the Retry Policy.
• No Ordering Guarantee: Events may arrive out of order, especially when retries are involved. Use the timestamps in the payload to order events.
• Idempotency: Webhook events carry unique identifiers (messageId for device reports, logId for temperature/humidity logs, id for alerts). Your receiving service should use these IDs as idempotency keys to safely de-duplicate messages in the event of network retries.

Security Best Practices

1. Use HTTPS: HTTPS endpoints with valid SSL/TLS certificates are strongly recommended so that payloads and credentials are encrypted in transit.
2. Verify Requests: Configure signatureSettings and verify the HMAC signature on every request, or configure a private authorization header (such as X-Webhook-Token) in headers to verify that incoming requests originate from Sensos.
3. Handle Payload Spikes Asynchronously: For high-volume label fleets, acknowledge incoming webhooks with 200 OK or 202 Accepted immediately, enqueue the raw payload into a messaging queue (e.g. SQS, Kafka, RabbitMQ), and process telemetry asynchronously.