Webhooks vanuit regels

Een regel kan een URL aanroepen wanneer hij activeert. Zo hoort uw eigen systeem direct van een gebeurtenis, bijvoorbeeld een hoge temperatuur of een apparaat dat de verbinding verliest.

Voordat u begint

• HAM Systems schakelt webhooks per account in. Toont de app Webhooks zijn niet ingeschakeld voor uw account? Neem dan contact op met ondersteuning.
• U hebt een https://-adres nodig dat POST-verzoeken van internet accepteert.

Een webhook aan een regel toevoegen

1. Open het Menu. Tik in de groep Hulpmiddelen op Cloudregels.
2. Open een regel of maak een nieuwe regel. Zie een regel maken.
3. Tik bij de acties op Actie toevoegen.
4. Kies in de lijst Webhook.
5. Typ in het veld URL het adres van uw systeem.
6. Wilt u ook een aanroep wanneer de regel reset? Tik dan op Resetactie toevoegen en kies opnieuw Webhook.
7. Tik op Opslaan.

Computer

Telefoon

Computer

Telefoon

Is het adres niet juist, dan toont de app URL is niet geldig.

Het verzoek

Het platform stuurt een POST met een 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": []
}

Veld	Inhoud
event	triggered wanneer de regel activeert. resolved wanneer een actie Bij reset wordt uitgevoerd.
rule.id, rule.name	Het nummer en de naam van de regel
rule.serialno	Het apparaat van de regel
rule.this_data	De voorwaarden van de regel
device_data	De huidige status van elk apparaat van de regel, met het serienummer als sleutel. Dezelfde indeling als de updates van de WebSocket.
messages	Fouten, bijvoorbeeld Failed to get state of e11:123 for rule #4321 wanneer de status van een apparaat niet beschikbaar is

De waarden in R zijn ruw. In het voorbeeld betekent T: 912 9,12 °C. Zie de definities in de REST API.

Het platform verwijdert de WiFi-gegevens van het apparaat (netwerknaam, wachtwoord en bedrijfsgegevens) uit device_data.

De webhook beveiligen

Het verzoek heeft geen handtekening (HMAC). Zo controleert u dat het verzoek van uw regel komt:

1. Maak een lang willekeurig geheim, bijvoorbeeld met openssl rand -hex 32.
2. Zet het geheim in de querystring van het adres: https://example.com/ham-hook?token=YOUR_SECRET.
3. Weiger in uw systeem elk verzoek dat niet de juiste token heeft.

Opgepast

Alle personen die de regel kunnen zien, zien ook het adres met het geheim. Verandert de groep personen met toegang? Verander dan het geheim.

Regels en limieten

• Het adres moet met https:// beginnen.
• Het platform roept geen lokale en privéadressen aan: 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 en de bijbehorende IPv6-adressen (::1, fe80:, fc00::/7).
• Maximaal 5 aanroepen per 60 seconden voor elke webhookactie van een regel.
• Maximaal 30 webhookaanroepen per 60 seconden voor elk account.
• Het platform slaat de aanroepen boven de limieten over. Het stuurt ze niet later.
• Het platform controleert de HTTP-status van uw antwoord niet en stuurt het verzoek niet opnieuw.
• Een actie kan een vertraging hebben (NA). Een regel heeft in totaal maximaal 12 acties.

Testen

Gebruik voor een eerste test een openbare dienst die de ontvangen verzoeken toont. Maak een regel met een eenvoudige voorwaarde en bekijk de body van het verzoek.

Zie ook

• Regelacties
• Live gegevens (WebSocket)
• Beveiliging