Webhook instellen

Een webhook hoort bij de hele organisatie. Hij krijgt de gekozen gebeurtenissen van alle gateways en alle alarmregels. Voor elk systeem dat berichten moet krijgen, voeg je een eigen webhook toe. Meer gegevens bij een bericht haal je op met de REST API, zoals beschreven in REST API en webhooks.

Wat je nodig hebt

• De rol Eigenaar of Beheerder. Alleen die rollen zien Webhooks onder Instellingen. In het demo-account voeg je geen webhook toe.
• Een adres op internet dat POST-verzoeken met JSON ontvangt en voldoet aan de eisen aan het adres.

Gebeurtenissen

De tabel laat zien welke gebeurtenissen een webhook verstuurt en wanneer.

Gaat een teruggekeerd alarm weer naar Actief, dan volgt geen nieuw alert.triggered. Wanneer een alarm van status wisselt, staat in Zo werken alarmen.

Elk bericht is een POST-verzoek met JSON. Het veld type bevat de eventnaam en data de details. De volgorde van aankomst staat niet vast, dus bepaal met het veld timestamp wat het laatst gebeurde. Een voorbeeld staat op de webhookpagina onder Voorbeeldbericht. Alle velden staan in de API-referentie.

Een adres in de actie Webhook van een automatisering gebruikt het portaal niet. Het stuurt automation.triggered naar elke webhook onder Instellingen > Webhooks die deze gebeurtenis ontvangt. Een automatisering maak je bij Automatiseringen aanmaken.

Eisen aan het adres

Het portaal stuurt alleen naar een adres dat vanaf internet bereikbaar is. Een geblokkeerd adres krijgt geen enkel bericht, en Test toont dan de reden.

• Het adres begint met https:// of http://. Gebruik https://, want over http:// gaat het bericht onversleuteld over internet.
• De host is een openbare naam of een openbaar IP-adres. Geblokkeerd zijn localhost en namen op .local, .localhost en .internal. Ook privé-IP-adressen zoals 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16 en 100.64.0.0/10 zijn geblokkeerd.
• Je systeem antwoordt binnen 10 seconden met een status van 200 tot 299. Antwoord eerst en verwerk het bericht daarna.
• Het adres stuurt niet door. Het portaal volgt geen doorverwijzing, dus een antwoord als 301 of 302 telt als mislukt.

Webhook toevoegen

Na deze stappen staat de webhook in de lijst en kent je systeem het geheim waarmee het berichten controleert.

1. Webhookpagina openen

   Ga naar Instellingen > Webhooks.

2. Toevoegen starten

   Klik op Webhook toevoegen. Het venster Webhook toevoegen opent.

3. Naam invullen

   Vul bij Naam een naam in waaraan je het ontvangende systeem herkent.

4. Adres invullen

   Vul bij Adres (URL) het volledige adres in, bijvoorbeeld https://voorbeeld.nl/webhooks/modbuscloud. Zolang Naam leeg is of het adres niet met http:// of https:// begint, blijft Webhook aanmaken grijs.

5. Keuze beperken

   Wil je niet alle gebeurtenissen ontvangen, vink dan Alle gebeurtenissen uit. De lijst met gebeurtenissen verschijnt, met Alarm gaat af al aangevinkt.

6. Gebeurtenissen aanvinken

   Heb je Alle gebeurtenissen uitgevinkt, vink dan de gebeurtenissen aan die je systeem moet krijgen. Wil je Alarm gaat af niet, vink het dan pas daarna uit. Gaat het laatste vinkje uit, dan staat Alle gebeurtenissen weer aan.

7. Webhook aanmaken

   Klik op Webhook aanmaken. De webhook staat nu in de lijst, met Nog niets verstuurd eronder.

8. Geheim kopiëren

   Klik bij de webhook op Geheim kopiëren. Het geheim begint met whsec_ en staat nu op je klembord.

9. Geheim opslaan

   Sla het geheim op in het ontvangende systeem. Daarmee controleert het elk bericht.

Het geheim blijft bij de webhook staan, zodat Geheim kopiëren later ook werkt. Adres en gebeurtenissen pas je achteraf niet aan. Wil je ze veranderen, verwijder de webhook dan met Verwijderen en voeg een nieuwe toe. De nieuwe webhook krijgt een eigen geheim, dus kopieer dat opnieuw naar je systeem.

Webhook testen

Een test laat zien of je systeem bereikbaar is en het bericht accepteert.

1. Test versturen

   Klik bij de webhook op Test. Het portaal stuurt meteen een ondertekend bericht met het type webhook.test.

2. Uitkomst lezen

   Lees de melding die verschijnt. Test aangekomen noemt het antwoord van je systeem en de tijd in milliseconden. Achter Test niet aangekomen staat de reden.

Krijgt het portaal antwoord, dan staan onder een webhook die aan staat het moment van verzenden en de status van het antwoord. Een test werkt ook als de webhook uit staat. Een test telt niet mee bij de mislukte berichten en zet die telling ook niet terug.

Berichten op echtheid controleren

Elk bericht is ondertekend volgens Standard Webhooks, met het geheim van de webhook. De handtekening staat in de headers webhook-id, webhook-timestamp en webhook-signature. Klopt de handtekening niet, dan komt het bericht niet van ModbusCloud of is het onderweg veranderd. Weiger het dan.

Een bibliotheek van Standard Webhooks doet de controle in één aanroep. Geef haar de ruwe body zoals die binnenkomt. Lees je de JSON eerst in en bouw je hem opnieuw op, dan veranderen de bytes en klopt de handtekening niet. Voorbeeldcode voor Node.js en Python staat in de API-referentie.

Mislukte berichten

Komt een bericht niet aan, dan probeert het portaal het opnieuw na 30 seconden, 2 minuten, 10 minuten, 1 uur en 6 uur. Dat zijn zes pogingen in ruim zeven uur. Elke poging heeft dezelfde webhook-id. Bewaar de ids die je hebt verwerkt en negeer een bericht waarvan je de id al kent.

Mislukt ook de zesde poging, dan telt het bericht als mislukt. Onder de webhook staat in rood hoeveel berichten op rij mislukten. Bij tien zet het portaal de webhook uit en staat er Uit. Een bericht dat wel aankomt, zet de telling terug op nul.

Webhook weer aanzetten

Na deze stappen verstuurt een uitgezette webhook weer berichten. Hij gaat nooit vanzelf weer aan.

1. Systeem herstellen

   Herstel het ontvangende systeem, zodat het weer op tijd antwoordt. Klopt het adres niet, voeg de webhook dan opnieuw toe.

2. Test versturen

   Klik bij de webhook op Test. Ga pas verder als de melding met Test aangekomen begint.

3. Webhook aanzetten

   Zet de schakelaar rechts in de regel van de webhook aan. Uit verdwijnt onder de webhook.

Aanzetten zet de telling van mislukte berichten niet terug. Mislukt het eerstvolgende bericht bij alle zes pogingen, dan gaat de webhook meteen weer uit. Met dezelfde schakelaar zet je een webhook ook zelf uit.