Creating Webhooks

You can create webhooks to be notified of alerts that occur in your Samsara account. This is particularly useful if you are looking to build integrations that relay a special alert event, such as when a vehicle arrives at a given location, or if your container temperature exceeds a given amount. For a complete list of all alerts that occur in Samsara, please refer to this Alerts Summary page.

Webhooks can be viewed and created via the Samsara dashboard.  Navigate to the Gear icon and click on Webhooks. Click on (+ Add Webhook) to create a webhook. Each webhook must have a name and route to a https URL.

Once a webhook has been created, individual alerts can be configured to send to a given webhook URL. To do so, navigate to the Bell icon to create a new alert or configure an existing alert. 

Note: This is not yet available for the Unsafe DVIR alert.

Responding to Webhook Events

You should acknowledge the receipt of a webhook request with a 2xx response code. If a webhook is not acknowledged, then Samsara will continue to retry in an exponential backoff fashion. 

Payloads

Samsara webhooks return JSON-encoded responses.

Example Payloads

See here for details on payload attributes.

Geofence Alert:

{
  "eventId": "f4bfadf8-ac64-4436-9bfa-42c0f37d3a33",
  "eventMs": 1486029722000,
  "eventType": "Alert",
  "event": {
    "alertConditionDescription": "Vehicle is inside geofence",
    "alertConditionId": "DeviceLocationInsideGeofence",
    "alertEventUrl": "https://cloud.samsara.com/groups/4185/alerts/incidents/v2/1000/1/222/1483228800000",
    "details": "'Truck ABC' is 5 miles away from Acme Bread",
    "device": {
      "id": 2000,
      "name": "Truck ABC",
      "serial": "ABC123",
      "vin": "1M8GDM9AXKP042788"
    },
    "orgId": 4000,
    "resolved": false,
    "startMs": 1486029722000,
    "summary": "'Truck ABC' is inside Acme Bread geofence"
  }
}

Vehicle Battery Alert: 

{
  "eventId": "746bd028-44df-4df4-9dc8-c4c887d9bff0",
  "eventMs": 1587151453491,
  "eventType": "Alert",
  "event": {
    "alertEventUrl": "https://cloud.samsara.com/o/00001/alerts/incidents/v2/30750/1/212014918214835/1587151393206/link?dl=eyJkZWVwTGlua1R5cGUiOiJBbGVydENvbmRpdGlvblR5cGVfQmF0dGVyeVZvbHRhZ2VCZWxvdyIsImdyb3VwSWQiOjE2NzM3fQ==",
    "alertConditionDescription": "Battery voltage below",
    "alertConditionId": "BatteryVoltageBelow",
    "details": "'Truck ABC' vehicle battery level has fallen below 15.000 V for more than 0 minutes. It is currently 12.052 V.",
    "device": {
      "id": 212014918214835,
      "name": "Truck ABC",
      "serial": "ABC123",
      "vin": "2JEA93JALLAL211A"
    },
    "orgId": 123,
    "resolved": false,
    "startMs": 1587151393206,
    "summary": "'Truck ABC' vehicle battery level has fallen below 15.000 V for more than 0 minutes. It is currently 12.052 V."
  }
}

Speeding Alert:

{
  "eventId": "f4bfadf8-ac64-4436-9bfa-42c0f37d3a33",
  "eventMs": 1486029722000,
  "eventType": "Alert",
  "event": {
    "alertConditionDescription": "Vehicle speed",
    "alertConditionId": "DeviceSpeedAbove",
    "alertEventUrl": "https://cloud.samsara.com/groups/4185/alerts/incidents/v2/1000/1/222/1483228800000",
    "details": "'Truck ABC' was speeding 65MPH in a 50MPH speed limit zone",
    "driver": {
      "id": 5000,
      "name": "Speed Demon"
    },
    "orgId": 4000,
    "resolved": false,
    "startMs": 1486029722000,
    "summary": "'Truck ABC' was speeding 65MPH in a 50MPH speed limit zone"
  }
}

Route Stop Arrival Alert:

{
  "eventId": "f4bfadf8-ac64-4436-9bfa-42c0f37d3a33",
  "eventMs": 1486029722000,
  "eventType": "Alert",
  "event": {
    "alertConditionDescription": "Dispatch Route ETA threshold",
    "alertConditionId": "DispatchRouteETAThreshold",
    "alertEventUrl": "https://cloud.samsara.com/groups/4185/alerts/incidents/v2/1000/1/222/1483228800000",
    "details": "'Truck ABC' is 15 minutes away from ACME Bread",
    "route": {
      "id": 6000,
      "name": "Bread Route"
    },
    "orgId": 4000,
    "resolved": false,
    "startMs": 1486029722000,
    "summary": "'Truck ABC' is 15 minutes away from ACME Bread"
  }
}

Temperature Alert:

{
  "eventId": "f4bfadf8-ac64-4436-9bfa-42c0f37d3a33",
  "eventMs": 1486029722000,
  "eventType": "Alert",
  "event": {
    "alertConditionDescription": "Ambient temperature is above",
    "alertConditionId": "TemperatureAbove",
    "alertEventUrl": "https://cloud.samsara.com/groups/4185/alerts/incidents/v2/1000/1/222/1483228800000",
    "details": "'Temperature probe' has been above 40 degrees fahrenheit for 15 minutes",
    "sensor": {
      "id": 7000,
      "name": "Temperature probe",
      "serial": "ABC123"
    },
    "orgId": 4000,
    "resolved": false,
    "startMs": 1486029722000,
    "summary": "'Temperature probe' has been above 40 degrees fahrenheit for 15 minutes"
  }
}

Attributes

Alert Condition Table

Verifying Webhook Signatures

Samsara uses webhook signatures in order to indicate that a payload has been sent by Samsara. Webhook payloads are signed by a HMAC-SHA256 encryption, which can be found in the "X-Samsara-Signature" header.

To verify that the payload is coming from us, you can compute the signature from the Webhook's secret key and verify it matches the signature in the header:

Below is some Python-based pseudocode to verify that your computed signature matches the one in the header of the body the payload.

import hashlib
import hmac
import base64
import codecs

timestamp = header["X-Samsara-Timestamp"]
plaintext_signature = "v1:%s:%s" % (timestamp, body)
secret = base64.b64decode(<YOUR_SECRET_KEY>)
signature = "v1=" + codecs.encode(hmac.new(secret, plaintext_signature, digestmod=hashlib.sha256).digest(), 'hex_codec')
assert(signature==header["X-Samsara-Signature"])