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
eventId |
Eindeutige Ereignis-ID |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
string |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
eventMs |
Zeit in Unix-Millisekunden, zu der das Ereignis generiert wurde. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
integer |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
eventType |
Wird immer „Warnmeldung“ (Alert) sein. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
string |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
event |
Das Ereignis, das diese Warnmeldung ausgelöst hat. Attribute siehe unten. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|
Tabelle mit Warnmeldungen
Bezeichnung der Warnmeldung in Samsara |
ID der Warnmeldung |
Beschreibung der Warnmeldung |
Details |
Batteriestand |
BatteryLow |
„Batterie schwach“ |
„'{widgetName}'-Batteriestand ist niedrig.“ „'{widgetName}'-Batterie ist fast leer.“ |
Temperatur |
TemperatureBelow TemperatureAbove |
„Umgebungstemperatur ist niedrig“ „Umgebungstemperatur ist hoch“ |
„'{widgetName}'-Umgebungstemperatur liegt seit über {duration} Minuten über {tempValue} {tempUnit}.“ „'{widgetName}'-Umgebungstemperatur liegt seit über {duration} Minuten unter {tempValue} {tempUnit}.“ „'{widgetName}'-Sensortemperatur liegt seit über {duration} Minuten über {tempValue} {tempUnit}.“ „'{widgetName}'-Sensortemperatur liegt seit über {duration} Minuten unter {tempValue} {tempUnit}.“ |
Luftfeuchtigkeit |
HumidityBelow HumidityAbove |
„Luftfeuchtigkeit ist hoch“ „Luftfeuchtigkeit ist niedrig“ |
„'{widgetName}'-Luftfeuchtigkeit liegt seit über {duration} Minuten über {threshold} %. Sie beträgt aktuell {humidityValue} %“, „'{widgetName}'-Luftfeuchtigkeit liegt seit über {duration} Minuten unter {threshold} %. Sie beträgt aktuell {humidityValue} %“ |
Verbindung |
DeviceDisconnect |
„Gateway ist offline“ |
„Verbindung zum Sensor '{deviceName}' unterbrochen. Es werden für diesen Sensor keine Warnmeldungen in Echtzeit versendet, solange er offline ist.“ |
Fahrzeug nicht angeschlossen |
DeviceUnplugged |
„Gateway nicht angeschlossen“ |
„'{deviceName}' ist nicht angeschlossen“ „'{deviceName}' ist seit mehr als {duration} Minuten nicht angeschlossen.“ |
Geofence |
DeviceLocationInsideGeofence DeviceLocationOutsideGeofence |
„Fahrzeug ist innerhalb des Geofence-Bereichs“ „Fahrzeug ist außerhalb des Geofence-Bereichs“ |
„'{deviceName}' ist {insideOrOutside} des Geofence-Bereichs {geofenceName}.“ „'{deviceName}' ist seit mehr als {duration} Minuten {insideOrOutside} des Geofence-Bereichs {geofenceName}.“ |
Geschwindigkeit |
DeviceSpeedAbove DeviceSpeedAboveSpeedLimit |
„Fahrzeug-Geschwindigkeit“ „Fahrzeug-Geschwindigkeit über der Begrenzung“ |
„'{deviceName}'-Geschwindigkeit ist auf über {conditionSpeed} gestiegen.“ „'{deviceName}'-Geschwindigkeit beträgt mehr als {conditionSpeed}. Aktuell {currentSpeed}. Standort: {location}“ „'{deviceName}'-Geschwindigkeit liegt seit über {mins} Minuten über {conditionSpeed}.“ „'{deviceName}' hat die Höchstgeschwindigkeit um {speedOver} überschritten.“ „'{deviceName} hat die Höchstgeschwindigkeit für mehr als {duration} Minuten um {speedOver} überschritten.“ |
Mängel am Fahrzeug |
VehicleHasFault |
„Mangel am Fahrzeug“ |
|
Fahrzeugmotor im Leerlauf |
EngineIdle |
„Motor im Leerlauf“ |
„'{deviceName}'-Motor ist im Leerlauf.“ „'{deviceName}'-Motor ist seit über {durationMins} Minuten im Leerlauf.“ „'{deviceName}'-Motor ist seit über {durationMins} Minuten am Standort {location} im Leerlauf.“ |
Fahrzeugbatterie |
BatteryVoltageBelow |
„Batteriespannung niedrig“ |
„'{deviceName}'-Batteriespannung ist seit über {duration} Minuten unter {threshold} V. Sie beträgt aktuell {batteryValue} V.“ |
Bewegung |
DeviceMovement |
„Fahrzeug in Bewegung“ |
„'{deviceName}' ist in Bewegung.“ „'{deviceName}' ist seit über {duration} Minuten in Bewegung.“ |
Tür offen |
DoorActivated |
„Tür geöffnet“ |
„'{widgetName}'-Tür ist offen.“ „'{widgetName}-Tür ist seit über {duration} Minuten offen.“ |
Verbindung zur Dashcam unterbrochen |
DashcamDisconnected |
„Verbindung zur Dashcam unterbrochen“ |
"Verbindung zur Dashcam von '{deviceName}' wurde unterbrochen.“ |
Routenstopp-Ankunft |
DispatchRouteETAThreshold |
„Routenplanung geschätzte Ankunftszeit“ |
„Fahrzeug {deviceName} auf der Route {routeName} ist ungefähr {timeToDestination} Minuten von {stopName} entfernt |
Kühlcontainer-Alarm |
ReeferHasNewAlarm |
„Ein neuer Kühlcontainer-Alarm ist erfolgt“ |
|
Kühlcontainer-Temperatur |
ReeferTemperatureAboveSetPoint ReeferTemperatureBelowSetPoint |
„Ablufttemperatur des Kühlcontainers liegt über dem vorgesehenen Wert.“ „Ablufttemperatur des Kühlcontainers liegt unter dem vorgesehenen Wert.“ |
|
Gefahrensituation |
HarshEvent |
„Eine Gefahrensituation hat sich ereignet.“ |
„Eine Gefahrensituation wurde am Fahrzeug {deviceName} um {startTime} festgestellt.“, „Eine Gefahrensituation wurde am Fahrzeug {deviceName} um {startTime} festgestellt. Bericht des Vorfalls: {incidentLink}“ |
Planmäßige Wartung |
ScheduledMaintenanceDate ScheduledMaintenanceEngineHours ScheduledMaintenanceOdometer |
„Planmäßige Wartung ist erforderlich“ „Wartung ist gemäß Wartungsplan nach Motorbetriebsstunden erforderlich“ „Wartung ist gemäß Wartungsplan nach Meilen-/Kilometerstand erforderlich“ |
„Vorbeugende Wartung ist gemäß Plan {maintenanceTitle} für das Fahrzeug {deviceName} erforderlich“ „Vorbeugende Wartung ist gemäß Plan {maintenanceTitle} für {numVehicles} Fahrzeuge erforderlich, darunter: {vehicleNames}“ |
Dokumentübermittlung |
DriverDocumentSubmitted |
„Dokumentübermittlung“ |
„Ein {documentTemplateName}-Dokument wurde von {driverName} um {submissionTime} übermittelt. Dokument: {documentUrl} (ID: {documentId})“, |
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"])
Kommentare
0 Kommentare
Zu diesem Beitrag können keine Kommentare hinterlassen werden.