Webhooks 1.0 Reference

Submit Feedback. We are always open to product feedback — whether it’s more webhooks you want to see, enhancements to existing webhooks, or anything webhooks related! Submit feedback here.

`Alert` Events

Alert events primarily trigger webhook notifications. These events are triggered by the alerts you have configured in the Samsara dashboard. See the Webhooks guide for more details on creating and configuring alerts. An event with an eventType of Alert has the following fields:

Field	Description
`alertEventUrl`	A link to the alert in the Samsara dashboard.
`alertConditionDescription`	A human-readable string describing the condition that triggered the alert.
`alertConditionId`	The ID of the condition that triggered the alert. Indicates the alert type.
`details`	A human-readable string with dynamic details on the alert.
`orgId`	The ID of your organization. Helpful in debugging when contacting support.
`resolved`	Whether the alert has been resolved. Always `false` in a webhook notification.
`startMs`	Unix epoch timestamp of when the event was triggered (from the gateway, mobile device, or originating cloud service). Different from `eventMs`.
`summary`	A brief summary of the event.
Additional fields	Depending on the alert type, additional fields may be available.

Example payload:

{
  "eventId": "bf72239c-bebd-4c22-b64c-6fc692ef7c46",
  "eventMs": 1587597109477,
  "eventType": "Alert",
  "event": {
    "alertEventUrl": "https://cloud.samsara.com/o/53729/alerts/incidents/v2/159827/1/212014918732717/1587596963539/link?dl=...",
    "alertConditionDescription": "Vehicle is inside geofence",
    "alertConditionId": "DeviceLocationInsideGeofence",
    "details": "'Little Red' is inside Parent's House.",
    "orgId": 53729,
    "resolved": false,
    "startMs": 1587596963539,
    "summary": "'Little Red' is inside Parent's House."
  }
}

The reference below documents each alert condition, the additional event fields it carries, and a representative payload. The device object — when present — always includes:

id (integer) — ID of the vehicle
name (string) — Name of the vehicle
serial (string) — Device serial number
vin (string) — VIN of the vehicle

Fault Codes

Field	Value
`alertConditionId`	`DeviceHasVehicleFault`
`alertConditionDescription`	`Vehicle has fault`
`device`	Vehicle device object
`details`	For J1939 vehicles, includes lamp names (`stop`, `warning`, `protect`, `emissions`) and per-fault `txId`, `spnId`, `spnDescription`, `fmiId`, `fmiDescription`, and `occurrenceCount`. For OBD-II, includes the `dtc` code and `dtcDescription`.

{
  "eventId": "e3645383-32f1-4c66-a5e6-983b2e456e77",
  "eventMs": 1600792716481,
  "eventType": "Alert",
  "event": {
    "alertConditionDescription": "Vehicle has fault",
    "alertConditionId": "DeviceHasVehicleFault",
    "details": "Vehicle 'Little Red' reported a fault. Check engine lights: warning, emissions. Vehicle faults: TxId: 11, SPN: 627 - Power Supply (obsolete), FMI: 4 (Voltage Below Normal), Count: 127.",
    "device": {
      "id": 281474977075805,
      "name": "Little Red",
      "serial": "G9MTH7CNKZ",
      "vin": "JTMBK32V895081147"
    },
    "orgId": 53729,
    "resolved": false,
    "startMs": 1600792612258,
    "summary": "Vehicle 'Little Red' reported a fault."
  }
}

Vehicle Unplugged

Field	Value
`alertConditionId`	`DeviceUnplugged`
`alertConditionDescription`	`Gateway unplugged`
`device`	Vehicle device object
`details`	`'{deviceName}' has been unplugged.`

{
  "eventType": "Alert",
  "event": {
    "alertConditionId": "DeviceUnplugged",
    "alertConditionDescription": "Gateway unplugged",
    "details": "'Little Red' has been unplugged.",
    "device": { "id": 281474977075805, "name": "Little Red", "serial": "G9MTH7CNKZ", "vin": "JTMBK32V895081147" },
    "orgId": 53729,
    "resolved": false,
    "summary": "'Little Red' has been unplugged."
  }
}

Harsh Event

Field	Value
`alertConditionId`	`HarshEvent`
`alertConditionDescription`	`Vehicle had a harsh event`
`device`	Vehicle device object
`harshEventType`	One of `harshAcceleration`, `harshBraking`, `harshTurning`, `crash`
`harshEventUrl`	Link to view the event in the Samsara dashboard
`harshEventLatitude` / `harshEventLongitude`	Decimal coordinates of the event

{
  "eventType": "Alert",
  "event": {
    "alertConditionId": "HarshEvent",
    "alertConditionDescription": "Vehicle had a harsh event",
    "details": "'Little Red' had a harsh acceleration event.",
    "device": { "id": 281474977075805, "name": "Little Red", "serial": "G9MTH7CNKZ", "vin": "JTMBK32V895081147" },
    "harshEventType": "harshAcceleration",
    "harshEventUrl": "https://cloud.samsara.com/...",
    "harshEventLatitude": 37.7749,
    "harshEventLongitude": -122.4194,
    "orgId": 53729,
    "resolved": false,
    "summary": "'Little Red' had a harsh acceleration event."
  }
}

Geofence

Field	Value
`alertConditionId`	`DeviceLocationInsideGeofence` or `DeviceLocationOutsideGeofence`
`alertConditionDescription`	`Vehicle is inside geofence` / `Vehicle is outside geofence`
`device`	Vehicle device object
`geofence`	Object with `id` and `name` of the geofence
`details`	`'{deviceName}' is inside/outside '{geofenceName}'.`

{
  "eventType": "Alert",
  "event": {
    "alertConditionId": "DeviceLocationInsideGeofence",
    "alertConditionDescription": "Vehicle is inside geofence",
    "details": "'Little Red' is inside Parent's House.",
    "device": { "id": 212014918732717, "name": "Little Red", "serial": "G9MTH7CNKZ", "vin": "JTMBK32V895081147" },
    "geofence": { "id": 12345, "name": "Parent's House" },
    "orgId": 53729,
    "resolved": false,
    "summary": "'Little Red' is inside Parent's House."
  }
}

Document Submission

Field	Value
`alertConditionId`	`DocumentSubmission`
`alertConditionDescription`	`Driver submitted a document`
`device`	Vehicle device object
`driver`	Driver object with `id` and `name`
`document`	Submitted document with `id`, `name`, and `submittedAtMs`

{
  "eventType": "Alert",
  "event": {
    "alertConditionId": "DocumentSubmission",
    "alertConditionDescription": "Driver submitted a document",
    "details": "Driver 'Sample Driver' submitted a document.",
    "device": { "id": 281474977075805, "name": "Little Red", "serial": "G9MTH7CNKZ", "vin": "JTMBK32V895081147" },
    "driver": { "id": 12345, "name": "Sample Driver" },
    "document": { "id": 67890, "name": "Bill of Lading", "submittedAtMs": 1600792716481 },
    "orgId": 53729,
    "resolved": false,
    "summary": "Driver 'Sample Driver' submitted a document."
  }
}

Speed

Field	Value
`alertConditionId`	`DeviceSpeedAboveSpeedLimit` or `DeviceSpeedAboveAbsoluteThreshold`
`alertConditionDescription`	`Vehicle is speeding`
`device`	Vehicle device object
`currentSpeedMetersPerSecond`	Vehicle speed at the time of the alert
`speedLimitMetersPerSecond`	Posted speed limit (for `DeviceSpeedAboveSpeedLimit`)
`speedThresholdMetersPerSecond`	Threshold (for `DeviceSpeedAboveAbsoluteThreshold`)

{
  "eventType": "Alert",
  "event": {
    "alertConditionId": "DeviceSpeedAboveSpeedLimit",
    "alertConditionDescription": "Vehicle is speeding",
    "details": "'Little Red' is speeding 78 mph in a 65 mph zone.",
    "device": { "id": 281474977075805, "name": "Little Red", "serial": "G9MTH7CNKZ", "vin": "JTMBK32V895081147" },
    "currentSpeedMetersPerSecond": 34.86,
    "speedLimitMetersPerSecond": 29.06,
    "orgId": 53729,
    "resolved": false,
    "summary": "'Little Red' is speeding 78 mph in a 65 mph zone."
  }
}

Movement

Field	Value
`alertConditionId`	`DeviceMovement` (movement detected)
`device`	Vehicle device object
`details`	`'{deviceName}' has started moving.`

{
  "eventType": "Alert",
  "event": {
    "alertConditionId": "DeviceMovement",
    "alertConditionDescription": "Vehicle is moving",
    "details": "'Little Red' has started moving.",
    "device": { "id": 281474977075805, "name": "Little Red" },
    "orgId": 53729,
    "resolved": false,
    "summary": "'Little Red' has started moving."
  }
}

Vehicle Engine Idle

Field	Value
`alertConditionId`	`DeviceVehicleEngineIdle`
`alertConditionDescription`	`Vehicle is idling`
`device`	Vehicle device object
`idleDurationMs`	Duration of idling in milliseconds

{
  "eventType": "Alert",
  "event": {
    "alertConditionId": "DeviceVehicleEngineIdle",
    "alertConditionDescription": "Vehicle is idling",
    "details": "'Little Red' has been idling for 5 minutes.",
    "device": { "id": 281474977075805, "name": "Little Red" },
    "idleDurationMs": 300000,
    "orgId": 53729,
    "resolved": false,
    "summary": "'Little Red' has been idling for 5 minutes."
  }
}

Device Battery Level

Field	Value
`alertConditionId`	`DeviceBatteryLowVoltage`
`alertConditionDescription`	`Vehicle battery is low`
`device`	Vehicle device object
`batteryMilliVolts`	Battery voltage in millivolts

{
  "eventType": "Alert",
  "event": {
    "alertConditionId": "DeviceBatteryLowVoltage",
    "alertConditionDescription": "Vehicle battery is low",
    "details": "'Little Red' battery is at 11.2V.",
    "device": { "id": 281474977075805, "name": "Little Red" },
    "batteryMilliVolts": 11200,
    "orgId": 53729,
    "resolved": false,
    "summary": "'Little Red' battery is at 11.2V."
  }
}

Dash Cam Disconnected

Field	Value
`alertConditionId`	`DashcamDisconnected`
`alertConditionDescription`	`Dashcam disconnected from vehicle`
`device`	Vehicle device object

{
  "eventType": "Alert",
  "event": {
    "alertConditionId": "DashcamDisconnected",
    "alertConditionDescription": "Dashcam disconnected from vehicle",
    "details": "Dashcam disconnected from 'Little Red'.",
    "device": { "id": 281474977075805, "name": "Little Red" },
    "orgId": 53729,
    "resolved": false
  }
}

Driver HOS Violation

Field	Value
`alertConditionId`	`DriverHOSViolation`
`alertConditionDescription`	`Driver has an HOS violation`
`driver`	Driver object with `id` and `name`
`violationType`	The HOS rule violated (e.g., shift drive, cycle, break)

{
  "eventType": "Alert",
  "event": {
    "alertConditionId": "DriverHOSViolation",
    "alertConditionDescription": "Driver has an HOS violation",
    "details": "Driver 'Sample Driver' has exceeded their shift drive limit.",
    "driver": { "id": 12345, "name": "Sample Driver" },
    "violationType": "shiftDriveLimit",
    "orgId": 53729,
    "resolved": false
  }
}

Vehicle Fuel Level

Field	Value
`alertConditionId`	`DeviceVehicleFuelLevelLow`
`alertConditionDescription`	`Vehicle fuel level is low`
`device`	Vehicle device object
`fuelLevelPercent`	Fuel percent at time of alert

{
  "eventType": "Alert",
  "event": {
    "alertConditionId": "DeviceVehicleFuelLevelLow",
    "alertConditionDescription": "Vehicle fuel level is low",
    "details": "'Little Red' has 10% fuel remaining.",
    "device": { "id": 281474977075805, "name": "Little Red" },
    "fuelLevelPercent": 10,
    "orgId": 53729,
    "resolved": false
  }
}

Temperature

Field	Value
`alertConditionId`	`SensorTemperatureAboveThreshold` or `SensorTemperatureBelowThreshold`
`sensor`	Sensor object with `id` and `name`
`temperatureMilliC`	Sensor temperature reading
`temperatureThresholdMilliC`	Configured threshold

{
  "eventType": "Alert",
  "event": {
    "alertConditionId": "SensorTemperatureAboveThreshold",
    "alertConditionDescription": "Sensor temperature is above threshold",
    "sensor": { "id": 22222, "name": "Reefer Sensor" },
    "temperatureMilliC": 5500,
    "temperatureThresholdMilliC": 4000,
    "orgId": 53729,
    "resolved": false
  }
}

Humidity

Field	Value
`alertConditionId`	`SensorHumidityAboveThreshold` or `SensorHumidityBelowThreshold`
`sensor`	Sensor object with `id` and `name`
`humidityRh`	Relative humidity reading
`humidityThresholdRh`	Configured threshold

{
  "eventType": "Alert",
  "event": {
    "alertConditionId": "SensorHumidityAboveThreshold",
    "alertConditionDescription": "Sensor humidity is above threshold",
    "sensor": { "id": 22222, "name": "Warehouse Humidity" },
    "humidityRh": 78,
    "humidityThresholdRh": 60,
    "orgId": 53729,
    "resolved": false
  }
}

Connection

Field	Value
`alertConditionId`	`SensorDisconnected`
`alertConditionDescription`	`Sensor has been disconnected`
`sensor`	Sensor object with `id` and `name`

{
  "eventType": "Alert",
  "event": {
    "alertConditionId": "SensorDisconnected",
    "alertConditionDescription": "Sensor has been disconnected",
    "sensor": { "id": 22222, "name": "Reefer Sensor" },
    "orgId": 53729,
    "resolved": false
  }
}

Vehicle Battery

Field	Value
`alertConditionId`	`SensorBatteryLow`
`alertConditionDescription`	`Sensor battery is low`
`sensor`	Sensor object with `id` and `name`
`batteryMilliVolts`	Battery voltage

{
  "eventType": "Alert",
  "event": {
    "alertConditionId": "SensorBatteryLow",
    "alertConditionDescription": "Sensor battery is low",
    "sensor": { "id": 22222, "name": "Door Sensor" },
    "batteryMilliVolts": 2100,
    "orgId": 53729,
    "resolved": false
  }
}

Door Open

Field	Value
`alertConditionId`	`SensorDoorOpen`
`alertConditionDescription`	`Door is open`
`sensor`	Sensor object with `id` and `name`

{
  "eventType": "Alert",
  "event": {
    "alertConditionId": "SensorDoorOpen",
    "alertConditionDescription": "Door is open",
    "sensor": { "id": 22222, "name": "Trailer Door" },
    "orgId": 53729,
    "resolved": false
  }
}

Route Stop Arrival

Field	Value
`alertConditionId`	`RouteStopArrival`
`alertConditionDescription`	`Vehicle arrived at route stop`
`device`	Vehicle device object
`route`	Route object with `id` and `name`
`routeStop`	Stop object with `id`, `name`, `actualArrivalTimeMs`

{
  "eventType": "Alert",
  "event": {
    "alertConditionId": "RouteStopArrival",
    "alertConditionDescription": "Vehicle arrived at route stop",
    "device": { "id": 281474977075805, "name": "Little Red" },
    "route": { "id": 6009862266, "name": "Sample Route" },
    "routeStop": { "id": 6066522713, "name": "Buffalo Grove, IL, USA", "actualArrivalTimeMs": 1724869716400 },
    "orgId": 53729,
    "resolved": false
  }
}

Reefer Alarm

Field	Value
`alertConditionId`	`ReeferAlarm`
`alertConditionDescription`	`Reefer triggered an alarm`
`device`	Vehicle / trailer device object
`reeferAlarmCode`	Manufacturer-specific alarm code

{
  "eventType": "Alert",
  "event": {
    "alertConditionId": "ReeferAlarm",
    "alertConditionDescription": "Reefer triggered an alarm",
    "device": { "id": 281474977075805, "name": "Trailer 1" },
    "reeferAlarmCode": "A123",
    "orgId": 53729,
    "resolved": false
  }
}

Reefer Temperature

Field	Value
`alertConditionId`	`ReeferTemperatureOutOfRange`
`device`	Reefer trailer device object
`temperatureMilliC`	Reefer temperature
`setpointMilliC`	Reefer setpoint

{
  "eventType": "Alert",
  "event": {
    "alertConditionId": "ReeferTemperatureOutOfRange",
    "alertConditionDescription": "Reefer temperature out of range",
    "device": { "id": 281474977075805, "name": "Trailer 1" },
    "temperatureMilliC": 5000,
    "setpointMilliC": 1000,
    "orgId": 53729,
    "resolved": false
  }
}

Scheduled Maintenance

Field	Value
`alertConditionId`	`MaintenanceScheduledDue`
`alertConditionDescription`	`Vehicle has a scheduled maintenance due`
`device`	Vehicle device object
`maintenance`	Object with `name` and `dueAtMs`

{
  "eventType": "Alert",
  "event": {
    "alertConditionId": "MaintenanceScheduledDue",
    "alertConditionDescription": "Vehicle has a scheduled maintenance due",
    "device": { "id": 281474977075805, "name": "Little Red" },
    "maintenance": { "name": "Oil Change", "dueAtMs": 1700000000000 },
    "orgId": 53729,
    "resolved": false
  }
}

Unsafe DVIR

Field	Value
`alertConditionId`	`UnsafeDVIR`
`alertConditionDescription`	`Driver submitted an unsafe DVIR`
`device`	Vehicle device object
`driver`	Driver object
`dvir`	DVIR object including `id`, `submittedAtMs`, and `defects` array

{
  "eventType": "Alert",
  "event": {
    "alertConditionId": "UnsafeDVIR",
    "alertConditionDescription": "Driver submitted an unsafe DVIR",
    "device": { "id": 281474977075805, "name": "Little Red" },
    "driver": { "id": 12345, "name": "Sample Driver" },
    "dvir": {
      "id": 624372548,
      "submittedAtMs": 1724871169000,
      "defects": [{ "category": "Brakes", "comment": "Brake pads worn" }]
    },
    "orgId": 53729,
    "resolved": false
  }
}

Safe DVIR with Defects

Field	Value
`alertConditionId`	`SafeDVIRWithDefects`
`alertConditionDescription`	`Driver submitted a safe DVIR with defects`
`device`	Vehicle device object
`driver`	Driver object
`dvir`	DVIR object including `id`, `submittedAtMs`, and `defects` array

{
  "eventType": "Alert",
  "event": {
    "alertConditionId": "SafeDVIRWithDefects",
    "alertConditionDescription": "Driver submitted a safe DVIR with defects",
    "device": { "id": 281474977075805, "name": "Little Red" },
    "driver": { "id": 12345, "name": "Sample Driver" },
    "dvir": {
      "id": 624372548,
      "submittedAtMs": 1724871169000,
      "defects": [{ "category": "Lights", "comment": "Marker light dim" }]
    },
    "orgId": 53729,
    "resolved": false
  }
}

Panic Button Pressed

Field	Value
`alertConditionId`	`PanicButtonPressed`
`alertConditionDescription`	`Panic button was pressed`
`device`	Vehicle device object
`latitude` / `longitude`	Coordinates at time of press

{
  "eventType": "Alert",
  "event": {
    "alertConditionId": "PanicButtonPressed",
    "alertConditionDescription": "Panic button was pressed",
    "device": { "id": 281474977075805, "name": "Little Red" },
    "latitude": 37.7749,
    "longitude": -122.4194,
    "orgId": 53729,
    "resolved": false
  }
}

Webhook Reference

Data Streaming

`Alert` Events

Fault Codes

Vehicle Unplugged

Harsh Event

Geofence

Document Submission

Speed

Movement

Vehicle Engine Idle

Device Battery Level

Dash Cam Disconnected

Driver HOS Violation

Vehicle Fuel Level

Temperature

Humidity

Connection

Vehicle Battery

Door Open

Route Stop Arrival

Reefer Alarm

Reefer Temperature

Scheduled Maintenance

Unsafe DVIR

Safe DVIR with Defects

Panic Button Pressed

Webhook Reference

Data Streaming

Documentation Index

​Alert Events

​Fault Codes

​Vehicle Unplugged

​Harsh Event

​Geofence

​Document Submission

​Speed

​Movement

​Vehicle Engine Idle

​Device Battery Level

​Dash Cam Disconnected

​Driver HOS Violation

​Vehicle Fuel Level

​Temperature

​Humidity

​Connection

​Vehicle Battery

​Door Open

​Route Stop Arrival

​Reefer Alarm

​Reefer Temperature

​Scheduled Maintenance

​Unsafe DVIR

​Safe DVIR with Defects

​Panic Button Pressed

`Alert` Events

Fault Codes

Vehicle Unplugged

Harsh Event

Geofence

Document Submission

Speed

Movement

Vehicle Engine Idle

Device Battery Level

Dash Cam Disconnected

Driver HOS Violation

Vehicle Fuel Level

Temperature

Humidity

Connection

Vehicle Battery

Door Open

Route Stop Arrival

Reefer Alarm

Reefer Temperature

Scheduled Maintenance

Unsafe DVIR

Safe DVIR with Defects

Panic Button Pressed