Alerts Common Schema

Overview

Sensos provides real-time delivery of alerts via webhooks and data delivery rules. When specific conditions are met based on your shipment configuration and device sensor data, an alert event is evaluated and dispatched to your configured endpoint.

When an alert is triggered, an HTTP POST request is sent to your webhook URL with a JSON payload describing the alert event.

Common Alert Envelope Fields

Every alert payload shares a common top-level envelope structure:

Field Name	Description	Type	Nullable	Detailed Description
`id`	Alert Instance ID	String (UUID)	No	Unique identifier generated for every individual alert event.
`ruleId`	Monitoring Rule ID	String (UUID)	No	Unique identifier of the monitoring rule or threshold definition that triggered this alert.
`accountId`	Sensos Account ID	String (UUID)	No	Operational account ID that owns the monitored shipment or asset.
`scope.type`	Monitored Resource Scope	String	No	Target entity type being monitored (`"Shipment"` or `"Asset"`).
`scope.id`	Target Resource ID	String (UUID)	No	Unique identifier of the monitored shipment or asset.
`conditionType`	Alert Condition Discriminator	String	No	Operational alert trigger code (e.g. `TemperatureBreach`, `HumidityBreach`, `ShockDetection`, `Dwell`, `ParcelOpened`, `UnauthorizedStop`, `LightBreach`, `ShipmentArrival`, `ShipmentDeparture`, `Landing`).
`severity`	Severity Level	String	No	Alert criticality level: `"Info"`, `"Warning"`, `"Error"`, or `"Critical"`.
`firedTime`	Alert Evaluation Timestamp	String (ISO 8601 UTC)	No	UTC timestamp when the cloud rule engine confirmed the trigger condition.
`timestamp`	Measurement / Event Timestamp	String (ISO 8601 UTC)	No	UTC timestamp when the underlying measurement or event occurred on the device.
`properties`	Event-Specific Properties	Object	No	Key-value map containing telemetry values, thresholds, durations, or flight metadata specific to the `conditionType`.
`location.source`	Positioning Source	String	Yes	Positioning method used to resolve location: `"Cellular"`, `"GPS"`, or `"Wifi"`.
`location.latitude`	Latitude	Decimal / Float	Yes	Device latitude in decimal degrees.
`location.longitude`	Longitude	Decimal / Float	Yes	Device longitude in decimal degrees.
`location.accuracy`	Positioning Accuracy	Decimal / Float	Yes	Estimated horizontal accuracy radius in meters.

Alert Event Examples by Condition Type

Below are concrete examples of alert event payloads across environmental, security, lifecycle, and delivery assurance categories:

Temperature Alert

{
    "id": "9557cd83-aa04-4194-a628-0d2b1b8d05b2",
    "ruleId": "76511e3f-96dc-434b-84a5-33695dd45c21",
    "accountId": "5bfafad0-5194-49eb-99b6-f827c53e2bbd",
    "scope": {
        "type": "Shipment",
        "id": "357aebc5-692d-4b25-87d0-fc9ee7b3ada9"
    },
    "conditionType": "TemperatureBreach",
    "severity": "Error",
    "firedTime": "2025-04-19T05:01:47.3636325Z",
    "timestamp": "2025-04-19T04:56:51.1456072Z",
    "properties": {
       "reportId": "e5366302-965d-4318-9d7d-fcd6687a7e1c",
       "reportTime": "2025-04-19T04:56:51.1456072Z",
       "temperatureValue": 43,
       "minimumTemperatureThreshold": 20,
       "maximumTemperatureThreshold": 40,
       "allowedTemperatureTolerance": 0
    },
    "location": {
        "source": "Cellular",
        "latitude": 55.83749771,
        "longitude": 12.54119396,
        "accuracy": 180.0
    }
}

Temperature Alert with Consecutive Deviation

{
    "id": "9557cd83-aa04-4194-a628-0d2b1b8d05b2",
    "ruleId": "76511e3f-96dc-434b-84a5-33695dd45c21",
    "accountId": "5bfafad0-5194-49eb-99b6-f827c53e2bbd",
    "scope": {
        "type": "Shipment",
        "id": "357aebc5-692d-4b25-87d0-fc9ee7b3ada9"
    },
    "conditionType": "TemperatureBreach",
    "severity": "Error",
    "firedTime": "2025-04-19T05:01:47.3636325Z",
    "timestamp": "2025-04-19T04:56:51.1456072Z",
    "properties": {
       "reportId": "e5366302-965d-4318-9d7d-fcd6687a7e1c",
       "reportTime": "2025-04-19T04:56:51.1456072Z",
       "minimumTemperatureThreshold": 20,
       "maximumTemperatureThreshold": 40,
       "allowedTemperatureTolerance": 0,
       "consecutiveBreachThreshold": 600,
       "consecutiveBreachTime": 1800,
       "lastTemperatureInBreach": 42
    }
}

Temperature Alert with Cumulative Deviation

{
    "id": "9557cd83-aa04-4194-a628-0d2b1b8d05b2",
    "ruleId": "76511e3f-96dc-434b-84a5-33695dd45c21",
    "accountId": "5bfafad0-5194-49eb-99b6-f827c53e2bbd",
    "scope": {
        "type": "Shipment",
        "id": "357aebc5-692d-4b25-87d0-fc9ee7b3ada9"
    },
    "conditionType": "TemperatureBreachAccumulated",
    "severity": "Error",
    "firedTime": "2025-04-19T05:01:47.3636325Z",
    "timestamp": "2025-04-19T04:56:51.1456072Z",
    "properties": {
       "reportId": "e5366302-965d-4318-9d7d-fcd6687a7e1c",
       "reportTime": "2025-04-19T04:56:51.1456072Z",
       "minimumTemperatureThreshold": 20,
       "maximumTemperatureThreshold": 40,
       "allowedTemperatureTolerance": 0,
       "accumulatedBreachThreshold": 600,
       "accumulatedBreachTime": 1800,
       "lastTemperatureInBreach": 42
    }
}

Humidity Alert

{
    "id": "9557cd83-aa04-4194-a628-0d2b1b8d05b2",
    "ruleId": "76511e3f-96dc-434b-84a5-33695dd45c21",
    "accountId": "5bfafad0-5194-49eb-99b6-f827c53e2bbd",
    "scope": {
        "type": "Shipment",
        "id": "357aebc5-692d-4b25-87d0-fc9ee7b3ada9"
    },
    "conditionType": "HumidityBreach",
    "severity": "Error",
    "firedTime": "2025-04-19T05:01:47.3636325Z",
    "timestamp": "2025-04-19T04:56:51.1456072Z",
    "properties": {
       "reportId": "e5366302-965d-4318-9d7d-fcd6687a7e1c",
       "reportTime": "2025-04-19T04:56:51.1456072Z",
       "humidityValue": 82,
       "minimumHumidityThreshold": 20,
       "maximumHumidityThreshold": 70
    },
    "location": {
        "source": "Cellular",
        "latitude": 55.83749771,
        "longitude": 12.54119396,
        "accuracy": 180.0
    }
}

Shock Alert

{
    "id": "9557cd83-aa04-4194-a628-0d2b1b8d05b2",
    "ruleId": "76511e3f-96dc-434b-84a5-33695dd45c21",
    "accountId": "5bfafad0-5194-49eb-99b6-f827c53e2bbd",
    "scope": {
        "type": "Shipment",
        "id": "357aebc5-692d-4b25-87d0-fc9ee7b3ada9"
    },
    "conditionType": "ShockDetection",
    "severity": "Error",
    "firedTime": "2025-04-19T05:01:47.3636325Z",
    "timestamp": "2025-04-19T04:56:51.1456072Z",
    "properties": {
       "reportId": "e5366302-965d-4318-9d7d-fcd6687a7e1c",
       "reportTime": "2025-04-19T04:56:51.1456072Z",
       "shockMagnitude": 12000,
       "shockDuration": 30,
       "configuredShockThreshold": 10000,
       "configuredShockDurationThreshold": 20
    },
    "location": {
        "source": "Cellular",
        "latitude": 55.83749771,
        "longitude": 12.54119396,
        "accuracy": 180.0
    }
}

Security Alert – Parcel Opened before it reaches its destination

{
    "id": "9557cd83-aa04-4194-a628-0d2b1b8d05b2",
    "ruleId": "76511e3f-96dc-434b-84a5-33695dd45c21",
    "accountId": "5bfafad0-5194-49eb-99b6-f827c53e2bbd",
    "scope": {
        "type": "Shipment",
        "id": "357aebc5-692d-4b25-87d0-fc9ee7b3ada9"
    },
    "conditionType": "ParcelOpened",
    "severity": "Error",
    "firedTime": "2025-04-19T05:01:47.3636325Z",
    "timestamp": "2025-04-19T04:56:51.1456072Z",
    "properties": {
       "reportId": "e5366302-965d-4318-9d7d-fcd6687a7e1c",
       "reportTime": "2025-04-19T04:56:51.1456072Z",
       "parcelOpenedStage": "BeforeArrival"
    },
    "location": {
        "source": "Cellular",
        "latitude": 55.83749771,
        "longitude": 12.54119396,
        "accuracy": 180.0
    }
}

Security Alert – Unauthorized Location

{
    "id": "9557cd83-aa04-4194-a628-0d2b1b8d05b2",
    "ruleId": "76511e3f-96dc-434b-84a5-33695dd45c21",
    "accountId": "5bfafad0-5194-49eb-99b6-f827c53e2bbd",
    "scope": {
        "type": "Shipment",
        "id": "357aebc5-692d-4b25-87d0-fc9ee7b3ada9"
    },
    "conditionType": "UnauthorizedStop",
    "severity": "Error",
    "firedTime": "2025-04-19T05:01:47.3636325Z",
    "timestamp": "2025-04-19T04:56:51.1456072Z",
    "properties": {
       "reportId": "e5366302-965d-4318-9d7d-fcd6687a7e1c",
       "reportTime": "2025-04-19T04:56:51.1456072Z",
       "totalBreachTime": 7200,
       "breachThreshold": 3600,
       "metersToNearestPointOfInterest": 50000,
       "nearestPointOfInterestName": "My Warehouse"
    },
    "location": {
        "source": "Cellular",
        "latitude": 55.83749771,
        "longitude": 12.54119396,
        "accuracy": 180.0
    }
}

Security Alert – Light Exposure Before Arrival

{
    "id": "9557cd83-aa04-4194-a628-0d2b1b8d05b2",
    "ruleId": "76511e3f-96dc-434b-84a5-33695dd45c21",
    "accountId": "5bfafad0-5194-49eb-99b6-f827c53e2bbd",
    "scope": {
        "type": "Shipment",
        "id": "357aebc5-692d-4b25-87d0-fc9ee7b3ada9"
    },
    "conditionType": "LightBreach",
    "severity": "Error",
    "firedTime": "2025-04-19T05:01:47.3636325Z",
    "timestamp": "2025-04-19T04:56:51.1456072Z",
    "properties": {
       "reportId": "e5366302-965d-4318-9d7d-fcd6687a7e1c",
       "reportTime": "2025-04-19T04:56:51.1456072Z",
       "lightBreachStage": "BeforeArrival"
    },
    "location": {
        "source": "GPS",
        "latitude": 55.83749771,
        "longitude": 12.54119396,
        "accuracy": 100.0
    }
}

Lifecycle Alert – Arrival at Destination

{
    "id": "9557cd83-aa04-4194-a628-0d2b1b8d05b2",
    "ruleId": "76511e3f-96dc-434b-84a5-33695dd45c21",
    "accountId": "5bfafad0-5194-49eb-99b6-f827c53e2bbd",
    "scope": {
        "type": "Shipment",
        "id": "357aebc5-692d-4b25-87d0-fc9ee7b3ada9"
    },
    "conditionType": "ShipmentArrival",
    "severity": "Error",
    "firedTime": "2025-04-19T05:01:47.3636325Z",
    "timestamp": "2025-04-19T04:56:51.1456072Z",
    "properties": {
       "reportId": "e5366302-965d-4318-9d7d-fcd6687a7e1c",
       "reportTime": "2025-04-19T04:56:51.1456072Z",
       "pointOfInterest": "Sensos Logistics Warehouse Canter, Berlin"
    },
    "location": {
        "source": "Cellular",
        "latitude": 55.83749771,
        "longitude": 12.54119396,
        "accuracy": 180.0
    }
}

Lifecycle Alert – Departure from Origin

{
    "id": "9557cd83-aa04-4194-a628-0d2b1b8d05b2",
    "ruleId": "76511e3f-96dc-434b-84a5-33695dd45c21",
    "accountId": "5bfafad0-5194-49eb-99b6-f827c53e2bbd",
    "scope": {
        "type": "Shipment",
        "id": "357aebc5-692d-4b25-87d0-fc9ee7b3ada9"
    },
    "conditionType": "ShipmentDeparture",
    "severity": "Error",
    "firedTime": "2025-04-19T05:01:47.3636325Z",
    "timestamp": "2025-04-19T04:56:51.1456072Z",
    "properties": {
       "reportId": "e5366302-965d-4318-9d7d-fcd6687a7e1c",
       "reportTime": "2025-04-19T04:56:51.1456072Z",
       "pointOfInterest": "Sensos Logistics Warehouse Canter, Berlin"
    },
    "location": {
        "source": "Cellular",
        "latitude": 55.83749771,
        "longitude": 12.54119396,
        "accuracy": 180.0
    }
}

Lifecycle Alert – Landing

{
    "id": "9557cd83-aa04-4194-a628-0d2b1b8d05b2",
    "ruleId": "76511e3f-96dc-434b-84a5-33695dd45c21",
    "accountId": "5bfafad0-5194-49eb-99b6-f827c53e2bbd",
    "scope": {
        "type": "Shipment",
        "id": "357aebc5-692d-4b25-87d0-fc9ee7b3ada9"
    },
    "conditionType": "Landing",
    "severity": "Warning",
    "firedTime": "2025-04-19T05:01:47.3636325Z",
    "timestamp": "2025-04-19T04:56:51.1456072Z",
    "properties": {
       "reportId": "e5366302-965d-4318-9d7d-fcd6687a7e1c",
       "reportTime": "2025-04-19T04:56:51.1456072Z"
    },
    "location": {
        "source": "GPS",
        "latitude": 55.83749771,
        "longitude": 12.54119396,
        "accuracy": 80.0
    }
}

Lifecycle Alert – Package Opened After Arrival

{
    "id": "9557cd83-aa04-4194-a628-0d2b1b8d05b2",
    "ruleId": "76511e3f-96dc-434b-84a5-33695dd45c21",
    "accountId": "5bfafad0-5194-49eb-99b6-f827c53e2bbd",
    "scope": {
        "type": "Shipment",
        "id": "357aebc5-692d-4b25-87d0-fc9ee7b3ada9"
    },
    "conditionType": "ParcelOpened",
    "severity": "Error",
    "firedTime": "2025-04-19T05:01:47.3636325Z",
    "timestamp": "2025-04-19T04:56:51.1456072Z",
    "properties": {
       "reportId": "e5366302-965d-4318-9d7d-fcd6687a7e1c",
       "reportTime": "2025-04-19T04:56:51.1456072Z",
       "parcelOpenedStage": "AfterArrival"
    },
    "location": {
        "source": "Cellular",
        "latitude": 55.83749771,
        "longitude": 12.54119396,
        "accuracy": 180.0
    }
}

Lifecycle Alert – Light Exposure After Arrival

{
    "id": "9557cd83-aa04-4194-a628-0d2b1b8d05b2",
    "ruleId": "76511e3f-96dc-434b-84a5-33695dd45c21",
    "accountId": "5bfafad0-5194-49eb-99b6-f827c53e2bbd",
    "scope": {
        "type": "Shipment",
        "id": "357aebc5-692d-4b25-87d0-fc9ee7b3ada9"
    },
    "conditionType": "LightBreach",
    "severity": "Error",
    "firedTime": "2025-04-19T05:01:47.3636325Z",
    "timestamp": "2025-04-19T04:56:51.1456072Z",
    "properties": {
       "reportId": "e5366302-965d-4318-9d7d-fcd6687a7e1c",
       "reportTime": "2025-04-19T04:56:51.1456072Z",
       "lightBreachStage": "AfterArrival"
    },
    "location": {
        "source": "Cellular",
        "latitude": 55.83749771,
        "longitude": 12.54119396,
        "accuracy": 180.0
    }
}

Delivery Assurance Alert – Dwell

{
  "id": "9557cd83-aa04-4194-a628-0d2b1b8d05b2",
  "ruleId": "76511e3f-96dc-434b-84a5-33695dd45c21",
  "accountId": "5bfafad0-5194-49eb-99b6-f827c53e2bbd",
  "scope": {
    "type": "Shipment",
    "id": "357aebc5-692d-4b25-87d0-fc9ee7b3ada9"
  },
  "conditionType": "Dwell",
  "severity": "Error",
  "firedTime": "2025-04-19T05:01:47.3636325Z",
  "timestamp": "2025-04-19T04:56:51.1456072Z",
  "properties": {
    "reportId": "e5366302-965d-4318-9d7d-fcd6687a7e1c",
    "reportTime": "2025-04-19T04:56:51.1456072Z",
    "totalDwellTime": 88313,
    "dwellThresholdTime": 86400
  },
  "location": {
     "source": "Cellular",
     "latitude": 55.83749771,
     "longitude": 12.54119396,
     "accuracy": 180.0
  }
}

Delivery Assurance Alert – FalsePickup

{
  "id": "9557cd83-aa04-4194-a628-0d2b1b8d05b2",
  "ruleId": "76511e3f-96dc-434b-84a5-33695dd45c21",
  "accountId": "5bfafad0-5194-49eb-99b6-f827c53e2bbd",
  "scope": {
    "type": "Shipment",
    "id": "357aebc5-692d-4b25-87d0-fc9ee7b3ada9"
  },
  "conditionType": "FalsePickup",
  "severity": "Error",
  "firedTime": "2025-04-19T05:01:47.3636325Z",
  "timestamp": "2025-04-19T04:56:51.1456072Z",
  "properties": {
    "reportId": "e5366302-965d-4318-9d7d-fcd6687a7e1c",
    "reportTime": "2025-04-19T04:56:51.1456072Z",
    "carrierEventTime": "2025-04-19T04:40:00Z"
  }
}

Delivery Assurance Alert – FalseOutForDelivery

{
  "id": "9557cd83-aa04-4194-a628-0d2b1b8d05b2",
  "ruleId": "76511e3f-96dc-434b-84a5-33695dd45c21",
  "accountId": "5bfafad0-5194-49eb-99b6-f827c53e2bbd",
  "scope": {
    "type": "Shipment",
    "id": "357aebc5-692d-4b25-87d0-fc9ee7b3ada9"
  },
  "conditionType": "FalseOutForDelivery",
  "severity": "Error",
  "firedTime": "2025-04-19T05:01:47.3636325Z",
  "timestamp": "2025-04-19T04:56:51.1456072Z",
  "properties": {
    "reportId": "e5366302-965d-4318-9d7d-fcd6687a7e1c",
    "reportTime": "2025-04-19T04:56:51.1456072Z",
    "carrierEventTime": "2025-04-19T04:40:00Z"
  }
}

Delivery Assurance Alert – FalseDelivery

{
  "id": "9557cd83-aa04-4194-a628-0d2b1b8d05b2",
  "ruleId": "76511e3f-96dc-434b-84a5-33695dd45c21",
  "accountId": "5bfafad0-5194-49eb-99b6-f827c53e2bbd",
  "scope": {
    "type": "Shipment",
    "id": "357aebc5-692d-4b25-87d0-fc9ee7b3ada9"
  },
  "conditionType": "FalseDelivery",
  "severity": "Error",
  "firedTime": "2025-04-19T05:01:47.3636325Z",
  "timestamp": "2025-04-19T04:56:51.1456072Z",
  "properties": {
    "reportId": "e5366302-965d-4318-9d7d-fcd6687a7e1c",
    "reportTime": "2025-04-19T04:56:51.1456072Z",
    "carrierEventTime": "2025-04-19T04:40:00Z"
  }
}

Delivery Assurance Alert – MissedDeliveryTime

{
  "id": "9557cd83-aa04-4194-a628-0d2b1b8d05b2",
  "ruleId": "76511e3f-96dc-434b-84a5-33695dd45c21",
  "accountId": "5bfafad0-5194-49eb-99b6-f827c53e2bbd",
  "scope": {
    "type": "Shipment",
    "id": "357aebc5-692d-4b25-87d0-fc9ee7b3ada9"
  },
  "conditionType": "MissedDeliveryTime",
  "severity": "Error",
  "firedTime": "2025-04-19T05:01:47.3636325Z",
  "timestamp": "2025-04-19T04:56:51.1456072Z",
  "properties": {
    "reportId": "e5366302-965d-4318-9d7d-fcd6687a7e1c",
    "reportTime": "2025-04-19T04:56:51.1456072Z",
    "requiredDeliveryTime": "2025-04-19T04:30:00Z"
  }
}

Delivery Assurance Alert – CarrierException

{
  "id": "9557cd83-aa04-4194-a628-0d2b1b8d05b2",
  "ruleId": "76511e3f-96dc-434b-84a5-33695dd45c21",
  "accountId": "5bfafad0-5194-49eb-99b6-f827c53e2bbd",
  "scope": {
    "type": "Shipment",
    "id": "357aebc5-692d-4b25-87d0-fc9ee7b3ada9"
  },
  "conditionType": "CarrierException",
  "severity": "Error",
  "firedTime": "2025-04-19T05:01:47.3636325Z",
  "timestamp": "2025-04-19T04:56:51.1456072Z",
  "properties": {
    "timestamp": "2025-04-19T04:56:51.1456072Z",
    "localTimestamp": "2025-04-19T05:56:51",
    "location": "Berlin, DE",
    "eventDescription": "Shipment delayed due to operational disruption."
  }
}

Delivery Assurance Alert – MissedFlight

{
  "id": "9557cd83-aa04-4194-a628-0d2b1b8d05b2",
  "ruleId": "76511e3f-96dc-434b-84a5-33695dd45c21",
  "accountId": "5bfafad0-5194-49eb-99b6-f827c53e2bbd",
  "scope": {
    "type": "Shipment",
    "id": "357aebc5-692d-4b25-87d0-fc9ee7b3ada9"
  },
  "conditionType": "MissedFlight",
  "severity": "Error",
  "firedTime": "2025-04-19T05:01:47.3636325Z",
  "timestamp": "2025-04-19T04:56:51.1456072Z",
  "properties": {
    "reportId": "e5366302-965d-4318-9d7d-fcd6687a7e1c",
    "reportTime": "2025-04-19T04:56:51.1456072Z",
    "flightNumber": "LH123",
    "departureTime": "2025-04-19T04:30:00Z"
  }
}

Delivery Assurance Alert – FlightConnectionRisk

{
  "id": "9557cd83-aa04-4194-a628-0d2b1b8d05b2",
  "ruleId": "76511e3f-96dc-434b-84a5-33695dd45c21",
  "accountId": "5bfafad0-5194-49eb-99b6-f827c53e2bbd",
  "scope": {
    "type": "Shipment",
    "id": "357aebc5-692d-4b25-87d0-fc9ee7b3ada9"
  },
  "conditionType": "FlightConnectionRisk",
  "severity": "Error",
  "firedTime": "2025-04-19T05:01:47.3636325Z",
  "timestamp": "2025-04-19T04:56:51.1456072Z",
  "properties": {
    "flightNumber": "LH456",
    "connectionTime": 20
  }
}