Webhooks aus Regeln

Eine Regel kann beim Auslösen eine URL aufrufen. So erfährt Ihr eigenes System sofort von einem Ereignis, zum Beispiel einer hohen Temperatur oder einer Geräte-Trennung.

Bevor Sie beginnen

• HAM Systems aktiviert Webhooks pro Konto. Wenn die App Webhooks sind für Ihr Konto nicht aktiviert zeigt, kontaktieren Sie den Support.
• Sie brauchen eine https://-Adresse, die POST-Anfragen aus dem Internet akzeptiert.

Einen Webhook zu einer Regel hinzufügen

1. Öffnen Sie das Menü. Tippen Sie in der Gruppe Werkzeuge auf Cloud-Regeln.
2. Öffnen Sie eine Regel oder erstellen Sie eine neue Regel. Siehe eine Regel erstellen.
3. Tippen Sie bei den Aktionen auf Aktion hinzufügen.
4. Wählen Sie in der Liste Webhook.
5. Geben Sie im Feld URL die Adresse Ihres Systems ein.
6. Wenn Sie auch einen Aufruf beim Zurücksetzen der Regel möchten, tippen Sie auf Reset-Aktion hinzufügen und wählen Sie wieder Webhook.
7. Tippen Sie auf Speichern.

Computer

Telefon

Computer

Telefon

Wenn die Adresse nicht korrekt ist, zeigt die App URL ist ungültig.

Die Anfrage

Die Plattform sendet ein POST mit einem JSON-Body (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": []
}

Feld	Inhalt
event	triggered, wenn die Regel auslöst. resolved, wenn eine Aktion Beim Zurücksetzen läuft.
rule.id, rule.name	Die Nummer und der Name der Regel
rule.serialno	Das Gerät der Regel
rule.this_data	Die Bedingungen der Regel
device_data	Der aktuelle Zustand jedes Geräts der Regel, nach Seriennummer geordnet. Dasselbe Format wie die Aktualisierungen des WebSocket.
messages	Fehler, zum Beispiel Failed to get state of e11:123 for rule #4321, wenn der Zustand eines Geräts nicht verfügbar ist

Die Werte in R sind roh. Im Beispiel bedeutet T: 912 9,12 °C. Siehe die Definitionen in der REST-API.

Die Plattform entfernt die WiFi-Daten des Geräts (Netzwerkname, Passwort und Unternehmensdaten) aus device_data.

Den Webhook absichern

Die Anfrage hat keine Signatur (HMAC). Um zu prüfen, dass die Anfrage von Ihrer Regel kommt:

1. Erstellen Sie ein langes zufälliges Geheimnis, zum Beispiel mit openssl rand -hex 32.
2. Fügen Sie das Geheimnis in den Query-String der Adresse ein: https://example.com/ham-hook?token=YOUR_SECRET.
3. Weisen Sie in Ihrem System jede Anfrage ab, die nicht den richtigen token hat.

Achtung

Alle Personen, die die Regel sehen können, sehen auch die Adresse mit dem Geheimnis. Wenn sich die Personen mit Zugriff ändern, ändern Sie das Geheimnis.

Regeln und Limits

• Die Adresse muss mit https:// beginnen.
• Die Plattform ruft keine lokalen und privaten Adressen auf: 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 und die verwandten IPv6-Adressen (::1, fe80:, fc00::/7).
• Bis zu 5 Aufrufe pro 60 Sekunden für jede Webhook-Aktion einer Regel.
• Bis zu 30 Webhook-Aufrufe pro 60 Sekunden für jedes Konto.
• Die Plattform überspringt die Aufrufe über den Limits. Sie sendet sie nicht später.
• Die Plattform prüft den HTTP-Status Ihrer Antwort nicht und sendet die Anfrage nicht erneut.
• Eine Aktion kann eine Verzögerung haben (NACH). Eine Regel hat insgesamt bis zu 12 Aktionen.

Test

Verwenden Sie für einen ersten Test einen öffentlichen Dienst, der die empfangenen Anfragen anzeigt. Erstellen Sie eine Regel mit einer einfachen Bedingung und sehen Sie den Body der Anfrage an.

Siehe auch

• Regelaktionen
• Live-Daten (WebSocket)
• Sicherheit