Webhooks

Création de webhooks

Afin de recevoir des alertes lorsque des événements se produisent concernant votre compte Samsara, vous avez la possibilité de créer des webhooks. C’est particulièrement utile si vous cherchez à développer des intégrations qui relaient une alerte spéciale en cas d’événement, par exemple, lorsqu’un véhicule arrive à un emplacement donné, ou si la température de votre conteneur dépasse un certain seuil. Pour une liste complète de toutes les alertes liées à la solution Samsara, reportez-vous à cette Page de synthèse des alertes.

Les webhooks peuvent être visualisés et créés via le tableau de bord Samsara.  Cliquez sur l’icône « roue » puis sélectionnez Webhooks. Cliquez sur (+ Ajouter un webhook) pour créer un webhook. À chaque webhook doit être associé un nom et un chemin vers une adresse URL https.

Une fois qu’un webhook a été créé, des alertes individuelles peuvent être configurées pour être envoyées vers une URL webhook spécifique. Pour ce faire, vous pouvez accéder à l’icône « cloche » et configurer une alerte existante ou en créer une nouvelle. 

Remarque : cette fonctionnalité n’est pas encore disponible pour l’alerte de rapport d’inspection concernant un véhicule non sûr.

Réponse à des événements webhook

Vous devez accuser réception d’une requête de webhook avec un code de réponse de type 2xx. Si la réception d’un webhook n’est pas confirmée, Samsara renverra la requête en appliquant un algorithme de repli exponentiel. 

Champ de données

Les webhooks Samsara renvoient des réponses dans le format de données JSON.

Exemple de champ de données

Cliquez ici pour accéder au détail des attributs de champ de données.

Alerte de géorepérage :

{
  "eventId": "f4bfadf8-ac64-4436-9bfa-42c0f37d3a33",
  "eventMs": 1486029722000,
  "eventType": "Alert",
  "event": {
    "alertConditionDescription": "Le véhicule est dans le périmètre géographique",
    "alertConditionId": "DeviceLocationInsideGeofence",
    "alertEventUrl": "https://cloud.samsara.com/groups/4185/alerts/incidents/v2/1000/1/222/1483228800000",
    "details": "'Le camion ABC' est à 8 kilomètres d’Acme Bread",
    "device": {
      "id": 2000,
      "name": "Camion ABC",
      "serial": "ABC123",
      "vin": "1M8GDM9AXKP042788"
    },
    "orgId": 4000,
    "resolved": false,
    "startMs": 1486029722000,
    "summary": "'Le camion ABC' est dans le périmètre géographique d’Acme Bread"
  }
}

Alerte batterie du véhicule : 

{
  "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": "Tension batterie inférieure à",
    "alertConditionId": "BatteryVoltageBelow",
    "details": "Le niveau de batterie du véhicule pour 'le camion ABC' a chuté en dessous de 15 000 V depuis plus de 0 minutes. Il est actuellement de 12 052 V.",
    "device": {
      "id": 212014918214835,
      "name": "Camion ABC",
      "serial": "ABC123",
      "vin": "2JEA93JALLAL211A"
    },
    "orgId": 123,
    "resolved": false,
    "startMs": 1587151393206,
    "summary": "Le niveau de batterie du véhicule pour 'le camion ABC' a chuté en dessous de 15 000 V depuis plus de 0 minutes. Il est actuellement de 12 052 V."
  }
}

Alerte excès de vitesse :

{
  "eventId": "f4bfadf8-ac64-4436-9bfa-42c0f37d3a33",
  "eventMs": 1486029722000,
  "eventType": "Alert",
  "event": {
    "alertConditionDescription": "Vitesse du véhicule",
    "alertConditionId": "DeviceSpeedAbove",
    "alertEventUrl": "https://cloud.samsara.com/groups/4185/alerts/incidents/v2/1000/1/222/1483228800000",
    "details": "'Le camion ABC' était en excès de vitesse à 105 km/h dans une zone de limitation à 80 km/h",
    "driver": {
      "id": 5000,
      "name": "Fou du volant"
    },
    "orgId": 4000,
    "resolved": false,
    "startMs": 1486029722000,
    "summary": "'Le camion ABC' était en excès de vitesse à 105 km/h dans une zone de limitation à 80 km/h"
  }
}

Alerte d’arrivée à un point d’arrêt d’itinéraire :

{
  "eventId": "f4bfadf8-ac64-4436-9bfa-42c0f37d3a33",
  "eventMs": 1486029722000,
  "eventType": "Alert",
  "event": {
    "alertConditionDescription": "Seuil de l’heure d’arrivée estimée pour l’itinéraire",
    "alertConditionId": "DispatchRouteETAThreshold",
    "alertEventUrl": "https://cloud.samsara.com/groups/4185/alerts/incidents/v2/1000/1/222/1483228800000",
    "details": "'Le camion ABC' est à 15 minutes d’ACME Bread",
    "route": {
      "id": 6000,
      "name": "Itinéraire Bread"
    },
    "orgId": 4000,
    "resolved": false,
    "startMs": 1486029722000,
    "summary": "'Le camion ABC' est à 15 minutes d’ACME Bread"
  }
}

Alerte de température :

{
  "eventId": "f4bfadf8-ac64-4436-9bfa-42c0f37d3a33",
  "eventMs": 1486029722000,
  "eventType": "Alert",
  "event": {
    "alertConditionDescription": "La température ambiante est supérieure à",
    "alertConditionId": "TemperatureAbove",
    "alertEventUrl": "https://cloud.samsara.com/groups/4185/alerts/incidents/v2/1000/1/222/1483228800000",
    "details": "'La sonde de température' a dépassé 4,4 degrés Celsius depuis 15 minutes",
    "sensor": {
      "id": 7000,
      "name": "Sonde de température",
      "serial": "ABC123"
    },
    "orgId": 4000,
    "resolved": false,
    "startMs": 1486029722000,
    "summary": "'La sonde de température' a dépassé 4,4 degrés Celsius depuis 15 minutes"
  }
}

Attributs

Tableau des situations d’alerte

Vérification de signatures webhook

Samsara utilise des signatures webhook pour indiquer qu’un champ de données a été envoyé par Samsara. Les champs de données de webhook sont signés au moyen de l’algorithme de chiffrement HMAC-SHA256, information accessible dans l’en-tête « X-Samsara-Signature ».

Afin de vérifier que le champ de données provient bien de nos services, vous pouvez calculer la signature à partir de la clé secrète du webhook et contrôler s’il correspond à la signature de l’en-tête :

Ci-dessous est présenté un code symbolique basé sur le langage Python pour vérifier que votre calcul de signature correspond à celui de l’en-tête dans le corps du champ de données.

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