Webhooks

Eine eigene Adresse aufrufen lassen, sobald sich ein Wert ändert

Ein Webhook lässt den Controller eine Adresse Ihrer Wahl aufrufen, sobald sich ein bestimmter Wert ändert. Ihr System muss dafür weder eine Verbindung halten noch abfragen; es braucht nur einen HTTP-Endpunkt, den der Controller erreicht.

Webhooks werden nur über die API verwaltet. In der App und in der Konfigurationsoberfläche gibt es dafür keine Seite. Die Aufrufe brauchen ein Konto der Gruppe „admin“, siehe Admin und normaler Benutzer.

Webhook anlegen

addWebHook legt einen Webhook an und gibt seine ID zurück:

Parameter	Bedeutung
type	component für den Wert einer Komponente
cid	Komponente, zum Beispiel C5
property	Wert der Komponente, zum Beispiel state
url	Adresse, die der Controller aufruft
enabled	optional, Standard true

Über HTTP sieht das so aus:

curl -s -X POST http://<controller-ip>/api/v1/addWebHook \
  -H 'auth-username: <benutzer>' -H 'auth-password: <kennwort>' \
  -H 'Content-Type: application/json' \
  -d '{"type":"component","cid":"C5","property":"state","url":"http://192.168.0.20:8080/nomos-hook"}'

{"id":25}

Fehlen cid oder property, antwortet der Controller mit {"errorCode":106,"errorText":"Parameter(s) error"}, bei einem unbekannten type mit Fehlercode 112. Der Typ join ist für mRemote-Anlagen gedacht und wird hier nicht beschrieben.

Der Webhook bleibt über Neustarts erhalten, bis Sie ihn entfernen.

Der Aufruf

Ändert sich der Wert, ruft der Controller die Adresse per GET auf und hängt vier Parameter an:

GET /nomos-hook?id=25&cid=C5&property=state&content=1
User-Agent: <Name des Controllers>

Parameter	Inhalt
id	ID des Webhooks
cid	Komponente
property	Wert der Komponente
content	neuer Wert, so wie das Gerät ihn meldet

content ist der Rohwert des Geräts, nicht der aufbereitete Wert aus der API. Ein Schaltzustand kommt deshalb als 1 oder 0, nicht als true oder false.

Ihr Endpunkt sollte mit Status 200 antworten. Der Controller wartet höchstens 5 Sekunden und wertet die Antwort nicht aus. Einen gescheiterten Aufruf wiederholt er nicht, er vermerkt ihn nur in seinem Protokoll. War Ihr Endpunkt eine Zeit lang nicht erreichbar, holen Sie den aktuellen Stand über die API, etwa mit getAllComponents.

Ein Empfänger zum Ausprobieren, in Node.js:

require('http').createServer(function(req, res) {
    console.log(req.method, req.url, req.headers['user-agent']);
    res.end('ok');
}).listen(8080);

Verwalten

Aufruf	Wirkung
getWebHooks	listet alle Webhooks mit ID, Typ, Ziel und Zustand
disableWebHook	hält einen Webhook an ({"id":25}), er bleibt gespeichert
enableWebHook	schaltet ihn wieder ein
removeWebHook	entfernt ihn

curl -s -X POST http://<controller-ip>/api/v1/getWebHooks \
  -H 'auth-username: <benutzer>' -H 'auth-password: <kennwort>'

[{"id":25,"created":"2026-10-08T12:47:01.252Z","lastUpdate":"2026-10-08T12:47:01.252Z",
  "type":"component","url":"http://192.168.0.20:8080/nomos-hook","enabled":true,
  "cid":"C5","property":"state"}]

Einen Webhook ändern können Sie nicht; entfernen Sie ihn und legen Sie ihn neu an.

Sicherheit

• Der Aufruf trägt keine Anmeldung und keine Signatur. Ihr Endpunkt kann nicht erkennen, ob er wirklich vom Controller kommt. Nehmen Sie deshalb einen schwer zu erratenden Pfad oder Parameter in die Adresse auf und lassen Sie den Endpunkt nur aus dem Netz des Controllers erreichbar sein.
• Bei https:// prüft der Controller das Zertifikat des Ziels. Ein selbstsigniertes Zertifikat lässt den Aufruf scheitern.
• Die Adresse muss vom Controller aus erreichbar sein. Ein Ziel im Internet setzt voraus, dass der Controller ins Internet darf.