Webhooks

Webhooks erstellen

Sie können Webhooks erstellen, um über Warnmeldungen in Ihrem Samsara-Konto benachrichtigt zu werden. Dies ist besonders nützlich, wenn Sie Integrationen für spezielle Ereignisse erstellen möchten, zum Beispiel wenn ein Fahrzeug an einem bestimmten Ort ankommt, oder wenn Ihre Container-Temperatur einen bestimmten Wert übersteigt. Eine vollständige Liste aller Warnmeldungen in Samsara finden Sie auf dieser Seite, die eine Übersicht der Warnmeldungen enthält.

Webhooks werden im Samsara Dashboard angezeigt und können dort erstellt werden. Klicken Sie auf das Zahnradsymbol und dann auf Webhooks. Klicken Sie nun auf (+ Add Webhook) (+ Webhook hinzufügen), um einen Webhook zu erstellen. Jeder Webhook muss einen Namen und eine https-URL haben.

Sobald ein Webhook erstellt ist, können einzelne Warnmeldungen konfiguriert werden zur Übermittlung an eine bestimmte Webhook-URL. Gehen Sie dazu auf das Glockensymbol, um eine neue Warnmeldung zu erstellen oder eine vorhandene Warnmeldung zu konfigurieren.

Hinweis: Diese Option ist für Warnmeldungen mit „Unsicher“-Inspektionsberichten noch nicht verfügbar.

Antwort auf Webhook-Ereignisse

Sie sollten den Erhalt einer Webhook-Anfrage durch einen 2xx-Antwort-Code bestätigen. Wenn ein Webhook nicht bestätigt wird, versucht Samsara erneut, die Sendung zu übertragen (Exponential Backoff). 

Payloads

Samsara Webhooks schicken JSON-kodierte Antworten.

Payload-Beispiele

Informationen zu den Payload-Attributen finden Sie hier.

Geofence-Warnmeldung:

{
  "eventId": "f4bfadf8-ac64-4436-9bfa-42c0f37d3a33",
  "eventMs": 1486029722000,
  "eventType": "Alert",
  "event": {
    "alertConditionDescription": "Fahrzeug ist innerhalb des Geofence-Bereichs",
    "alertConditionId": "DeviceLocationInsideGeofence",
    "alertEventUrl": "https://cloud.samsara.com/groups/4185/alerts/incidents/v2/1000/1/222/1483228800000",
    "details": "'Truck ABC' ist 5 Meilen von Acme Bread entfernt",
    "device": {
      "id": 2000,
      "name": "Truck ABC",
      "serial": "ABC123",
      "vin": "1M8GDM9AXKP042788"
    },
    "orgId": 4000,
    "resolved": false,
    "startMs": 1486029722000,
    "summary": "'Truck ABC' ist innerhalb des Geofence-Bereichs Acme Bread"
  }
}

Fahrzeugbatterie-Warnmeldung: 

{
  "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": "Batteriespannung niedrig",
    "alertConditionId": "BatteryVoltageBelow",
    "details": "'Truck ABC'-Batteriespannung ist seit über 0 Minuten unter 15.000 V. Sie beträgt aktuell 12.052 V.",
    "device": {
      "id": 212014918214835,
      "name": "Truck ABC",
      "serial": "ABC123",
      "vin": "2JEA93JALLAL211A"
    },
    "orgId": 123,
    "resolved": false,
    "startMs": 1587151393206,
    "summary": "'Truck ABC'-Batteriespannung ist seit über 0 Minuten unter 15.000 V. Sie beträgt aktuell 12.052 V."
  }
}

Geschwindigkeits-Warnmeldung:

{
  "eventId": "f4bfadf8-ac64-4436-9bfa-42c0f37d3a33",
  "eventMs": 1486029722000,
  "eventType": "Alert",
  "event": {
    "alertConditionDescription": "Fahrzeug-Geschwindigkeit",
    "alertConditionId": "DeviceSpeedAbove",
    "alertEventUrl": "https://cloud.samsara.com/groups/4185/alerts/incidents/v2/1000/1/222/1483228800000",
    "details": "'Truck ABC' ist 70 km/h in einer 50er-Zone gefahren",
    "driver": {
      "id": 5000,
      "name": "Speed Demon"
    },
    "orgId": 4000,
    "resolved": false,
    "startMs": 1486029722000,
    "summary": "'Truck ABC' ist 70 km/h in einer 50er-Zone gefahren"
  }
}

Warnmeldung bez. Routenstopp-Ankunft:

{
  "eventId": "f4bfadf8-ac64-4436-9bfa-42c0f37d3a33",
  "eventMs": 1486029722000,
  "eventType": "Alert",
  "event": {
    "alertConditionDescription": "Routenplanung geschätzte Ankunftszeit",
    "alertConditionId": "DispatchRouteETAThreshold",
    "alertEventUrl": "https://cloud.samsara.com/groups/4185/alerts/incidents/v2/1000/1/222/1483228800000",
    "details": "'Truck ABC' ist 15 Minuten von Acme Bread entfernt",
    "route": {
      "id": 6000,
      "name": "Bread Route"
    },
    "orgId": 4000,
    "resolved": false,
    "startMs": 1486029722000,
    "summary": "'Truck ABC' ist 15 Minuten von Acme Bread entfernt"
  }
}

Warnmeldung bez. Temperatur:

{
  "eventId": "f4bfadf8-ac64-4436-9bfa-42c0f37d3a33",
  "eventMs": 1486029722000,
  "eventType": "Alert",
  "event": {
    "alertConditionDescription": "Umgebungstemperatur ist hoch",
    "alertConditionId": "TemperatureAbove",
    "alertEventUrl": "https://cloud.samsara.com/groups/4185/alerts/incidents/v2/1000/1/222/1483228800000",
    "details": "'Umgebungstemperatur' liegt seit 15 Minuten über 4 Grad Celsius",
    "sensor": {
      "id": 7000,
      "name": "Temperature probe",
      "serial": "ABC123"
    },
    "orgId": 4000,
    "resolved": false,
    "startMs": 1486029722000,
    "summary": "'Umgebungstemperatur' liegt seit 15 Minuten über 4 Grad Celsius"
  }
}

Attribute

Tabelle mit Warnmeldungen

Webhook-Signaturen prüfen

Samsara nutzt Webhook-Signaturen, um zu signalisieren, dass eine Payload von Samsara versendet wurde. Webhook-Payloads werden mit einer HMAC-SHA256-Verschlüsselung signiert, die im „X-Samsara-Signatur“-Header zu finden ist.

Um sicherzugehen, dass die Payload von uns kommt, können Sie die Signatur mit dem geheimen Schlüssel des Webhooks berechnen und prüfen, ob sie mit der Signatur im Header übereinstimmt:

Unten sehen Sie einen Python-basierten Pseudocode, mit dem überprüft werden kann, ob Ihre berechnete Signatur mit der im Header der Payload übereinstimmt.

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"])