Data Delivery Overview

Sensos provides real-time, automated data delivery to stream hardware telemetry, periodic device reports, high-frequency 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:

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.
Temperature Logging: Sequential, timestamped temperature time-series logs recorded during transit for cold chain compliance and excursion analysis.
Humidity Logging: Sequential, timestamped relative humidity (%RH) logs recorded during transit for environmental monitoring.
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 supports two primary delivery mechanisms:

HTTPS Webhook (Webhook): Pushes JSON payloads via standard HTTP POST requests to your public endpoint. Supports custom authentication headers and automatic retry policies.
AWS IoT Core (AwsIot): Publishes telemetry directly to an MQTT topic in your AWS IoT Core account using mutual TLS (mTLS) client certificates. For step-by-step setup, see AWS IoT Core Data Delivery.

Configuring Data Delivery Rules via API

Data delivery rules are scoped to your Sensos operational account (accountId). You can create and manage rules programmatically via the Sensos REST API.

Endpoint

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

1. Webhook Delivery Rule Example

To configure a webhook receiver for device reports:

{
  "name": "Production TMS Webhook",
  "dataSourceType": "DeviceReports",
  "action": {
    "type": "Webhook",
    "url": "https://api.yourcompany.com/webhooks/sensos",
    "customHeaders": {
      "X-Webhook-Token": "<SHARED_SECRET_TOKEN>"
    }
  }
}

Request Fields

Field Name	Type	Required	Description
`name`	String	Yes	Descriptive identifier for the delivery rule.
`dataSourceType`	String	Yes	The stream to deliver: `"DeviceReports"`, `"TemperatureLogging"`, `"HumidityLogging"`, or `"Alerts"`.
`action.type`	String	Yes	Destination adapter type. Must be `"Webhook"` for HTTP endpoints.
`action.url`	String	Yes	Publicly accessible HTTPS URL where Sensos will send `POST` requests.
`action.customHeaders`	Object	No	Key-value pairs included in the request headers of every delivery attempt (e.g. static API keys, shared secrets).

2. AWS IoT Core Delivery Rule Example

To configure an AWS IoT Core export for temperature logging:

{
  "name": "AWS IoT Temperature Export",
  "dataSourceType": "TemperatureLogging",
  "action": {
    "type": "AwsIot",
    "endpoint": "a3k7odshaiipe8-ats.iot.us-east-1.amazonaws.com",
    "topic": "sensos/data/temperature",
    "clientCertificateId": "cf3d8e2c-6f7e-4b91-81e9-4d35f558f9f3"
  }
}

(Requires uploading a client certificate first; see AWS IoT Core Data Delivery).

Reliability & Retry Semantics

Sensos guarantees reliable webhook delivery using an automated exponential backoff mechanism:

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: If your endpoint returns a 5xx server error, 429 Too Many Requests, connection timeout, or network reset, Sensos enters an exponential retry loop.
Retry Schedule: Failed deliveries are retried up to 13 times over approximately 34 hours before being marked as failed. For the complete timing table, see the Retry Policy.
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

Enforce HTTPS: Sensos only delivers webhooks to secure HTTPS endpoints with valid SSL/TLS certificates.
Verify Custom Headers: Configure a private authorization header (such as X-Webhook-Token) in customHeaders to verify that incoming requests originate from Sensos.
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.