Webhooks fra regler

En regel kan kalle en URL når den utløses. Slik får ditt eget system vite om en hendelse med en gang, for eksempel en høy temperatur eller en enhet som kobler seg fra.

Før du starter

• HAM Systems slår på webhooks for hver konto. Hvis appen viser Webhooks er ikke aktivert for kontoen din, kontakt kundestøtte.
• Du trenger en https://-adresse som tar imot POST-forespørsler fra internett.

Legg til en webhook i en regel

1. Åpne Meny. I gruppen Verktøy, trykk på Skyregler.
2. Åpne en regel eller lag en ny regel. Se Opprett en regel.
3. I handlingene, trykk på Legg til handling.
4. I listen, velg Webhook.
5. I feltet URL, skriv adressen til systemet ditt.
6. Hvis du også vil ha et kall når regelen blir tilbakestilt, trykk på Legg til tilbakestillingshandling og velg Webhook igjen.
7. Trykk på Lagre.

Datamaskin

Telefon

Datamaskin

Telefon

Hvis adressen ikke er riktig, viser appen URL er ikke gyldig.

Forespørselen

Plattformen sender en POST med JSON-innhold (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": []
}

Felt	Innhold
event	triggered når regelen utløses. resolved når en handling Ved tilbakestilling kjører.
rule.id, rule.name	Nummeret og navnet på regelen
rule.serialno	Enheten for regelen
rule.this_data	Betingelsene for regelen
device_data	Den aktuelle tilstanden for hver enhet i regelen, med serienummeret som nøkkel. Det samme formatet som oppdateringene fra WebSocket.
messages	Feil, for eksempel Failed to get state of e11:123 for rule #4321 når tilstanden til en enhet ikke er tilgjengelig

Verdiene i R er rå. I eksempelet betyr T: 912 9,12 °C. Se definisjonene i REST API.

Plattformen fjerner WiFi-detaljene for enheten (nettverksnavn, passord og enterprise-detaljer) fra device_data.

Beskytt webhooken

Forespørselen har ingen signatur (HMAC). For å kontrollere at forespørselen kommer fra regelen din:

1. Lag en lang tilfeldig hemmelighet, for eksempel med openssl rand -hex 32.
2. Sett hemmeligheten i spørrestrengen til adressen: https://example.com/ham-hook?token=YOUR_SECRET.
3. I systemet ditt, avvis hver forespørsel som ikke har riktig token.

Advarsel

Alle personer som kan se regelen, kan også se adressen med hemmeligheten. Hvis personene med tilgang endres, endre hemmeligheten.

Regler og grenser

• Adressen må starte med https://.
• Plattformen kaller ikke lokale og private 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 og de tilsvarende IPv6-adressene (::1, fe80:, fc00::/7).
• Opptil 5 kall per 60 sekunder for hver webhook-handling i en regel.
• Opptil 30 webhook-kall per 60 sekunder for hver konto.
• Plattformen hopper over kallene over grensene. Den sender dem ikke senere.
• Plattformen kontrollerer ikke HTTP-statusen i svaret ditt og sender ikke forespørselen på nytt.
• En handling kan ha en forsinkelse (ETTER). En regel har opptil 12 handlinger totalt.

Test

For en første test, bruk en offentlig tjeneste som viser forespørslene som den tar imot. Lag en regel med en enkel betingelse og se på innholdet i forespørselen.

Se også

• Hva en regel gjør: varsel eller kommando
• Data i sanntid (WebSocket)
• Sikkerhet