Webhooks från regler

En regel kan anropa en URL när den utlöses. På så sätt får ditt eget system veta om en händelse direkt, till exempel en hög temperatur eller en frånkopplad enhet.

Innan du börjar

• HAM Systems slår på webhooks per konto. Om appen visar Webhooks är inte aktiverade för ditt konto, kontakta support.
• Du behöver en https://-adress som accepterar POST-begäranden från internet.

Lägg till en webhook i en regel

1. Öppna Meny. I gruppen Verktyg, tryck på Molnregler.
2. Öppna en regel eller skapa en ny regel. Se skapa en regel.
3. I åtgärderna, tryck på Lägg till åtgärd.
4. I listan, välj Webhook.
5. I fältet URL, skriv adressen till ditt system.
6. Om du också vill ha ett anrop när regeln återställs, tryck på Lägg till återställningsåtgärd och välj Webhook igen.
7. Tryck på Spara.

Dator

Telefon

Dator

Telefon

Om adressen inte är korrekt visar appen URL:en är inte giltig.

Begäran

Plattformen skickar en POST med ett JSON-innehåll (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": []
}

Fält	Innehåll
event	triggered när regeln utlöses. resolved när en åtgärd Vid återställning körs.
rule.id, rule.name	Regelns nummer och namn
rule.serialno	Regelns enhet
rule.this_data	Regelns villkor
device_data	Det aktuella tillståndet för varje enhet i regeln, med serienumret som nyckel. Samma format som uppdateringarna i WebSocket.
messages	Fel, till exempel Failed to get state of e11:123 for rule #4321 när en enhets tillstånd inte är tillgängligt

Värdena i R är råvärden. I exemplet betyder T: 912 9.12 °C. Se definitionerna i REST API.

Plattformen tar bort enhetens WiFi-uppgifter (nätverksnamn, lösenord och enterprise-uppgifter) från device_data.

Skydda din webhook

Begäran har ingen signatur (HMAC). För att kontrollera att begäran kommer från din regel:

1. Skapa en lång slumpmässig hemlighet, till exempel med openssl rand -hex 32.
2. Lägg hemligheten i adressens frågesträng: https://example.com/ham-hook?token=YOUR_SECRET.
3. I ditt system, avvisa varje begäran som inte har rätt token.

Caution

Alla personer som kan se regeln kan också se adressen med hemligheten. Om personerna med åtkomst ändras, byt hemligheten.

Regler och gränser

• Adressen måste börja med https://.
• Plattformen anropar inte lokala och privata adresser: 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 och motsvarande IPv6-adresser (::1, fe80:, fc00::/7).
• Upp till 5 anrop per 60 sekunder för varje webhook-åtgärd i en regel.
• Upp till 30 webhook-anrop per 60 sekunder för varje konto.
• Plattformen hoppar över anropen över gränserna. Den skickar dem inte senare.
• Plattformen kontrollerar inte HTTP-statusen i ditt svar och skickar inte begäran igen.
• En åtgärd kan ha en fördröjning (EFTER). En regel har upp till 12 åtgärder totalt.

Testa

För ett första test, använd en offentlig tjänst som visar de begäranden som den tar emot. Skapa en regel med ett enkelt villkor och titta på begärans innehåll.

Se också

• Regelåtgärder
• Data i realtid (WebSocket)
• Säkerhet