Webhook einrichten

Ein Webhook gehört zur gesamten Organisation. Er erhält die gewählten Ereignisse aller Gateways und aller Alarmregeln. Für jedes System, das Nachrichten bekommen soll, fügen Sie einen eigenen Webhook hinzu. Weitere Daten zu einer Nachricht holen Sie mit der REST-API ab, wie in REST-API und Webhooks beschrieben.

Was Sie brauchen

• Die Rolle Eigentümer oder Administrator. Nur diese Rollen sehen Webhooks unter Einstellungen. Im Demo-Konto fügen Sie keinen Webhook hinzu.
• Eine Adresse im Internet, die POST-Anfragen mit JSON empfängt und die Anforderungen an die Adresse erfüllt.

Ereignisse

Die Tabelle zeigt, welche Ereignisse ein Webhook sendet und wann.

Wechselt ein zurückgekehrter Alarm wieder zu Aktiv, folgt kein neues alert.triggered. Wann ein Alarm den Status wechselt, steht in So funktionieren Alarme.

Jede Nachricht ist eine POST-Anfrage mit JSON. Das Feld type enthält den Ereignisnamen und data die Details. Die Reihenfolge des Eintreffens ist nicht festgelegt. Bestimmen Sie daher mit dem Feld timestamp, was zuletzt passiert ist. Ein Beispiel steht auf der Webhook-Seite unter Beispielnachricht. Alle Felder stehen in der API-Referenz.

Eine Adresse in der Aktion Webhook einer Automatisierung verwendet das Portal nicht. Es sendet automation.triggered an jeden Webhook unter Einstellungen > Webhooks, der dieses Ereignis empfängt. Eine Automatisierung erstellen Sie unter Automatisierungen erstellen.

Anforderungen an die Adresse

Das Portal sendet nur an eine Adresse, die aus dem Internet erreichbar ist. Eine blockierte Adresse erhält keine einzige Nachricht, und Test zeigt dann den Grund.

• Die Adresse beginnt mit https:// oder http://. Verwenden Sie https://, denn über http:// geht die Nachricht unverschlüsselt durch das Internet.
• Der Host ist ein öffentlicher Name oder eine öffentliche IP-Adresse. Blockiert sind localhost und Namen auf .local, .localhost und .internal. Auch private IP-Adressen wie 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16 und 100.64.0.0/10 sind blockiert.
• Ihr System antwortet innerhalb von 10 Sekunden mit einem Status von 200 bis 299. Antworten Sie zuerst und verarbeiten Sie die Nachricht danach.
• Die Adresse leitet nicht weiter. Das Portal folgt keiner Weiterleitung, daher gilt eine Antwort wie 301 oder 302 als fehlgeschlagen.

Webhook hinzufügen

Nach diesen Schritten steht der Webhook in der Liste, und Ihr System kennt das Secret, mit dem es Nachrichten prüft.

1. Webhook-Seite öffnen

   Gehen Sie zu Einstellungen > Webhooks.

2. Hinzufügen starten

   Klicken Sie auf Webhook hinzufügen. Das Fenster Webhook hinzufügen öffnet sich.

3. Namen eingeben

   Geben Sie bei Name einen Namen ein, an dem Sie das empfangende System erkennen.

4. Adresse eingeben

   Geben Sie bei Adresse (URL) die vollständige Adresse ein, zum Beispiel https://beispiel.de/webhooks/modbuscloud. Solange Name leer ist oder die Adresse nicht mit http:// oder https:// beginnt, bleibt Webhook anlegen grau.

5. Auswahl einschränken

   Möchten Sie nicht alle Ereignisse empfangen, deaktivieren Sie Alle Ereignisse. Die Liste der Ereignisse erscheint, mit Alarm wird ausgelöst bereits aktiviert.

6. Ereignisse aktivieren

   Haben Sie Alle Ereignisse deaktiviert, aktivieren Sie die Ereignisse, die Ihr System erhalten soll. Möchten Sie Alarm wird ausgelöst nicht, deaktivieren Sie es erst danach. Wird das letzte Häkchen entfernt, ist Alle Ereignisse wieder aktiv.

7. Webhook anlegen

   Klicken Sie auf Webhook anlegen. Der Webhook steht nun in der Liste, mit Noch nichts gesendet darunter.

8. Secret kopieren

   Klicken Sie beim Webhook auf Secret kopieren. Das Secret beginnt mit whsec_ und liegt nun in Ihrer Zwischenablage.

9. Secret speichern

   Speichern Sie das Secret im empfangenden System. Damit prüft es jede Nachricht.

Das Secret bleibt beim Webhook gespeichert, sodass Secret kopieren auch später funktioniert. Adresse und Ereignisse ändern Sie nachträglich nicht. Möchten Sie sie ändern, entfernen Sie den Webhook mit Löschen und fügen Sie einen neuen hinzu. Der neue Webhook erhält ein eigenes Secret, kopieren Sie es also erneut in Ihr System.

Webhook testen

Ein Test zeigt, ob Ihr System erreichbar ist und die Nachricht akzeptiert.

1. Test senden

   Klicken Sie beim Webhook auf Test. Das Portal sendet sofort eine signierte Nachricht mit dem Typ webhook.test.

2. Ergebnis lesen

   Lesen Sie die Meldung, die erscheint. Test angekommen nennt die Antwort Ihres Systems und die Zeit in Millisekunden. Hinter Test nicht angekommen steht der Grund.

Erhält das Portal eine Antwort, stehen unter einem aktiven Webhook der Zeitpunkt des Sendens und der Status der Antwort. Ein Test funktioniert auch, wenn der Webhook aus ist. Ein Test zählt nicht bei den fehlgeschlagenen Nachrichten mit und setzt diese Zählung auch nicht zurück.

Nachrichten auf Echtheit prüfen

Jede Nachricht ist nach Standard Webhooks signiert, mit dem Secret des Webhooks. Die Signatur steht in den Headern webhook-id, webhook-timestamp und webhook-signature. Stimmt die Signatur nicht, stammt die Nachricht nicht von ModbusCloud oder wurde unterwegs verändert. Lehnen Sie sie dann ab.

Eine Bibliothek von Standard Webhooks übernimmt die Prüfung in einem Aufruf. Übergeben Sie ihr den rohen Body, so wie er ankommt. Lesen Sie das JSON zuerst ein und bauen es neu auf, ändern sich die Bytes und die Signatur stimmt nicht. Beispielcode für Node.js und Python steht in der API-Referenz.

Fehlgeschlagene Nachrichten

Kommt eine Nachricht nicht an, versucht das Portal es erneut nach 30 Sekunden, 2 Minuten, 10 Minuten, 1 Stunde und 6 Stunden. Das sind sechs Versuche in gut sieben Stunden. Jeder Versuch hat dieselbe webhook-id. Speichern Sie die verarbeiteten IDs und ignorieren Sie eine Nachricht, deren ID Sie schon kennen.

Schlägt auch der sechste Versuch fehl, gilt die Nachricht als fehlgeschlagen. Unter dem Webhook steht in Rot, wie viele Nachrichten in Folge fehlgeschlagen sind. Bei zehn schaltet das Portal den Webhook aus, und es steht Aus da. Eine Nachricht, die ankommt, setzt die Zählung auf null zurück.

Webhook wieder einschalten

Nach diesen Schritten sendet ein ausgeschalteter Webhook wieder Nachrichten. Er schaltet sich nie von selbst wieder ein.

1. System wiederherstellen

   Stellen Sie das empfangende System wieder her, sodass es rechtzeitig antwortet. Stimmt die Adresse nicht, fügen Sie den Webhook neu hinzu.

2. Test senden

   Klicken Sie beim Webhook auf Test. Machen Sie erst weiter, wenn die Meldung mit Test angekommen beginnt.

3. Webhook einschalten

   Schalten Sie den Schalter rechts in der Zeile des Webhooks ein. Aus verschwindet unter dem Webhook.

Das Einschalten setzt die Zählung der fehlgeschlagenen Nachrichten nicht zurück. Schlägt die nächste Nachricht bei allen sechs Versuchen fehl, schaltet sich der Webhook sofort wieder aus. Mit demselben Schalter schalten Sie einen Webhook auch selbst aus.