Webhook dalle regole

Una regola può chiamare un URL quando si attiva. In questo modo il Suo sistema viene a sapere subito di un evento, per esempio una temperatura alta o una disconnessione di un dispositivo.

Prima di iniziare

• HAM Systems attiva i webhook per ogni account. Se l’app mostra I webhook non sono abilitati per il tuo account, contatti l’assistenza.
• Ha bisogno di un indirizzo https:// che accetta richieste POST da internet.

Aggiungere un webhook a una regola

1. Apra il Menu. Nel gruppo Strumenti, tocchi Regole cloud.
2. Apra una regola o ne crei una nuova. Veda creare una regola.
3. Nelle azioni, tocchi Aggiungi azione.
4. Nell’elenco, selezioni Webhook.
5. Nel campo URL, scriva l’indirizzo del Suo sistema.
6. Se desidera una chiamata anche quando la regola si reimposta, tocchi Aggiungi azione di reset e selezioni di nuovo Webhook.
7. Tocchi Salva.

Computer

Telefono

Computer

Telefono

Se l’indirizzo non è corretto, l’app mostra L’URL non è valido.

La richiesta

La piattaforma invia un POST con un corpo 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": []
}

Campo	Contenuto
event	triggered quando la regola si attiva. resolved quando viene eseguita un’azione Al reset.
rule.id, rule.name	Il numero e il nome della regola
rule.serialno	Il dispositivo della regola
rule.this_data	Le condizioni della regola
device_data	Lo stato attuale di ogni dispositivo della regola, con il numero di serie come chiave. Lo stesso formato degli aggiornamenti WebSocket.
messages	Errori, per esempio Failed to get state of e11:123 for rule #4321 quando lo stato di un dispositivo non è disponibile

I valori in R sono grezzi. Nell’esempio, T: 912 significa 9.12 °C. Veda le definizioni nell’API REST.

La piattaforma rimuove da device_data i dati WiFi del dispositivo (nome della rete, password e dati enterprise).

Proteggere il webhook

La richiesta non ha una firma (HMAC). Per verificare che la richiesta provenga dalla Sua regola:

1. Crei un segreto casuale lungo, per esempio con openssl rand -hex 32.
2. Inserisca il segreto nella query string dell’indirizzo: https://example.com/ham-hook?token=YOUR_SECRET.
3. Nel Suo sistema, rifiuti ogni richiesta che non ha il token corretto.

Attenzione

Tutte le persone che possono vedere la regola possono vedere anche l’indirizzo con il segreto. Se le persone con accesso cambiano, cambi il segreto.

Regole e limiti

• L’indirizzo deve iniziare con https://.
• La piattaforma non chiama indirizzi locali e privati: 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 e i relativi indirizzi IPv6 (::1, fe80:, fc00::/7).
• Fino a 5 chiamate ogni 60 secondi per ogni azione webhook di una regola.
• Fino a 30 chiamate webhook ogni 60 secondi per ogni account.
• La piattaforma salta le chiamate oltre i limiti. Non le invia più tardi.
• La piattaforma non controlla lo stato HTTP della Sua risposta e non invia di nuovo la richiesta.
• Un’azione può avere un ritardo (DOPO). Una regola ha fino a 12 azioni in totale.

Prova

Per una prima prova, usi un servizio pubblico che mostra le richieste che riceve. Crei una regola con una condizione semplice e guardi il corpo della richiesta.

Vedere anche

• Azioni delle regole
• Dati in tempo reale (WebSocket)
• Sicurezza