Webhooks des règles

Une règle peut appeler une URL quand elle se déclenche. Ainsi votre propre système apprend un événement immédiatement, par exemple une température haute ou la déconnexion d’un appareil.

Avant de commencer

• HAM Systems active les webhooks par compte. Si l’application affiche Les webhooks ne sont pas activés pour votre compte, contactez le support.
• Vous avez besoin d’une adresse https:// qui accepte les requêtes POST depuis internet.

Ajouter un webhook à une règle

1. Ouvrez le Menu. Dans le groupe Outils, touchez Règles cloud.
2. Ouvrez une règle ou créez une nouvelle règle. Voir créer une règle.
3. Dans les actions, touchez Ajouter une action.
4. Dans la liste, choisissez Webhook.
5. Dans le champ URL, saisissez l’adresse de votre système.
6. Si vous voulez aussi un appel quand la règle se réinitialise, touchez Ajouter une action de réinitialisation et choisissez à nouveau Webhook.
7. Touchez Enregistrer.

Ordinateur

Téléphone

Ordinateur

Téléphone

Si l’adresse n’est pas correcte, l’application affiche L’URL n’est pas valide.

La requête

La plateforme envoie un POST avec un corps JSON (Content-Type: application/json) :

{
  "event": "triggered",
  "rule": {
    "id": 4321,
    "name": "Fridge 1 temperature",
    "serialno": "e11:123",
    "this_data": [ { "...": "the rule conditions" } ]
  },
  "device_data": {
    "e11:123": {
      "R": { "T": 912, "GI": 1, "GIC": 0, "GI2": 1, "GI2C": 0 },
      "O": [],
      "S": { "...": "the device settings" }
    }
  },
  "messages": []
}

Champ	Contenu
event	triggered quand la règle se déclenche. resolved quand une action À la réinitialisation s’exécute.
rule.id, rule.name	Le numéro et le nom de la règle
rule.serialno	L’appareil de la règle
rule.this_data	Les conditions de la règle
device_data	L’état actuel de chaque appareil de la règle, avec le numéro de série comme clé. Le même format que les mises à jour du WebSocket.
messages	Les erreurs, par exemple Failed to get state of e11:123 for rule #4321 quand l’état d’un appareil n’est pas disponible

Les valeurs dans R sont brutes. Dans l’exemple, T: 912 signifie 9,12 °C. Voir les définitions dans l’API REST.

La plateforme retire de device_data les informations WiFi de l’appareil (nom du réseau, mot de passe et informations d’entreprise).

Sécuriser le webhook

La requête n’a pas de signature (HMAC). Pour vérifier que la requête vient de votre règle :

1. Créez un long secret aléatoire, par exemple avec openssl rand -hex 32.
2. Mettez le secret dans la chaîne de requête de l’adresse : https://example.com/ham-hook?token=YOUR_SECRET.
3. Dans votre système, rejetez chaque requête qui n’a pas le bon token.

Attention

Toutes les personnes qui peuvent voir la règle peuvent aussi voir l’adresse avec le secret. Si les personnes avec accès changent, changez le secret.

Règles et limites

• L’adresse doit commencer par https://.
• La plateforme n’appelle pas les adresses locales et privées : localhost, 127.0.0.0/8, 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, 169.254.0.0/16, 100.64.0.0/10, 0.0.0.0/8 et les adresses IPv6 associées (::1, fe80:, fc00::/7).
• Jusqu’à 5 appels par 60 secondes pour chaque action webhook d’une règle.
• Jusqu’à 30 appels webhook par 60 secondes pour chaque compte.
• La plateforme ignore les appels au-dessus des limites. Elle ne les envoie pas plus tard.
• La plateforme ne vérifie pas le statut HTTP de votre réponse et n’envoie pas la requête à nouveau.
• Une action peut avoir un délai (APRÈS). Une règle a jusqu’à 12 actions au total.

Test

Pour un premier test, utilisez un service public qui montre les requêtes qu’il reçoit. Créez une règle avec une condition facile et regardez le corps de la requête.

Voir aussi

• Actions des règles
• Données en direct (WebSocket)
• Sécurité