WifiWhirl® Webhooks zur externen Steuerung

Nutze Webhooks, um dein WifiWhirl-Modul über HTTP-Anfragen fernzusteuern. Hier findest du alle Befehle und Parameter für die Integration.

Ab der Version 1.1.3 deines WifiWhirl-Moduls kannst du viele Funktionen bequem über Webhooks (HTTP-Aufrufe) fernsteuern. Dies ermöglicht die Integration in viele Smart-Home-Systeme, eigene Skripte oder den direkten Aufruf über einen Webbrowser.

Grundlagen

Webhooks sind eine einfache Methode, mit der Anwendungen über das HTTP-Protokoll miteinander kommunizieren können. Im Fall des WifiWhirl-Moduls sendest du eine speziell formatierte URL an das Modul, um eine Aktion auszulösen.

Wichtige Hinweise vorab:

• Ersetze in allen Beispiel-URLs wifiwhirl.local durch den Hostnamen oder die lokale IP-Adresse deines WifiWhirl-Moduls im Netzwerk. Den Hostnamen (oft wifiwhirl-xxxxxx.local) oder die IP-Adresse findest du z.B. in der Weboberfläche deines Routers oder beim Start des Moduls auf dem Pumpendisplay.
• Alle Webhook-Aufrufe erfolgen über die HTTP GET-Methode, sofern nicht anders angegeben.
• Die zu sendenden Befehle werden als JSON-Objekt im send-Parameter der URL übergeben. Die Struktur ist dabei immer {"CMD":<Befehlsnummer>,"VALUE":<Wert>}.

Verfügbare Webhook-Befehle

Die folgende Tabelle listet alle verfügbaren Befehle auf, die du per Webhook an dein WifiWhirl-Modul senden kannst:

Funktion	CMD	VALUE Typ	VALUE Beispiele & Hinweise	Beispiel-URL (mit wifiwhirl.local)
Pumpe Ein/Aus	4	Boolean	true (ein), false (aus)	http://wifiwhirl.local/hook/?send={"CMD":4,"VALUE":true}
Heizung & Pumpe Ein/Aus	3	Boolean	true (ein), false (aus)	http://wifiwhirl.local/hook/?send={"CMD":3,"VALUE":true}
AirJet-Düsen Ein/Aus	2	Boolean	true (ein), false (aus)	http://wifiwhirl.local/hook/?send={"CMD":2,"VALUE":true}
HydroJet-Düsen Ein/Aus	11	Boolean	true (ein), false (aus)	http://wifiwhirl.local/hook/?send={"CMD":11,"VALUE":true}
Ziel-Temperatur setzen	0	Unsigned Integer	Ganzzahl, z.B. 30 für 30°C	http://wifiwhirl.local/hook/?send={"CMD":0,"VALUE":30}
Display-Helligkeit setzen	12	Unsigned Integer	0 (aus) bis 8 (max. Helligkeit)	http://wifiwhirl.local/hook/?send={"CMD":12,"VALUE":8}
Umgebungstemp. setzen (°C)	15	Integer	Ganzzahl in °C, z.B. 20 für 20°C (-40 bis 60)	http://wifiwhirl.local/hook/?send={"CMD":15,"VALUE":20}
Tasten aktivieren/deaktivieren	26	Boolean	true (aktivieren), false (deaktivieren)	http://wifiwhirl.local/hook/?send={"CMD":26,"VALUE":false}
pH-Wert setzen	27	Unsigned Integer	Wert = pH × 10, z.B. 72 für pH 7,2	http://wifiwhirl.local/hook/?send={"CMD":27,"VALUE":72}
Chlorgehalt setzen	28	Unsigned Integer	Wert = Cl × 10 in mg/L, z.B. 15 für 1,5 mg/L	http://wifiwhirl.local/hook/?send={"CMD":28,"VALUE":15}
Cyanursäure (CYA) setzen	29	Unsigned Integer	Wert = CYA × 10 in mg/L, z.B. 300 für 30,0 mg/L	http://wifiwhirl.local/hook/?send={"CMD":29,"VALUE":300}
Alkalität setzen	30	Unsigned Integer	Wert in mg/L, z.B. 100 für 100 mg/L	http://wifiwhirl.local/hook/?send={"CMD":30,"VALUE":100}

Weitere Befehle

Diese Befehle sind seltener im Einsatz, funktionieren aber genauso. Befehle ohne Wert ignorieren VALUE - du kannst den Parameter dann einfach weglassen, z.B. http://wifiwhirl.local/hook/?send={"CMD":6}.

Funktion	CMD	VALUE Typ	Hinweise & Beispiel-JSON
Temperatureinheit umschalten	1	Boolean	true = °C, false = °F. Wird nicht von jedem Pumpenmodell übernommen. {"CMD":1,"VALUE":true}
Warteschlange leeren	5	-	Verwirft alle geplanten Befehle. {"CMD":5}
Modul neu starten	6	-	Speichert Einstellungen und Warteschlange, dann Neustart des Moduls. {"CMD":6}
Alle Zähler zurücksetzen	8	-	Laufzeiten, Energie (kWh) und Kosten auf 0. {"CMD":8}
Chlor-Timer zurücksetzen	9	-	Setzt den Timer für die letzte Chlorzugabe auf jetzt. {"CMD":9}
Filter-Timer zurücksetzen	10	-	Setzt den Timer für die letzte Filterreinigung auf jetzt. {"CMD":10}
Signalton / Melodie	13	Unsigned Integer	0 = kurzer Piep, 1 = Akkord. Jeder andere Wert spielt die Melodiedatei aus TXT. {"CMD":13,"VALUE":2,"TXT":"/furelise.mel"}
Umgebungstemp. setzen (°F)	14	Integer	Ganzzahl in °F (-40 bis 140). {"CMD":14,"VALUE":68}
Tagesverbrauch zurücksetzen	16	-	Setzt kWh und Kosten des laufenden Tages zurück. {"CMD":16}
Volle Heizleistung	18	Boolean	true = beide Heizelemente, false = eines. Nur bei Pumpen mit zwei Heizelementen. {"CMD":18,"VALUE":true}
Text auf dem Display anzeigen	19	-	Zeigt den Inhalt von TXT an, ohne sonst etwas zu schalten (max. 96 Zeichen). {"CMD":19,"TXT":"HALLO"}
Fertig-Zeitpunkt (Aufheizen planen)	20	-	Sonderfall: Der Zielzeitpunkt steht als Unix-Timestamp in XTIME, VALUE wird dabei überschrieben. Das Modul schätzt die Aufheizzeit (plus 2 h Reserve) und startet die Heizung rechtzeitig. {"CMD":20,"XTIME":1767250800}
Ein/Aus umschalten	22	-	Wie ein Druck auf die Power-Taste - ein Umschalter, kein Ein/Aus-Wert. {"CMD":22}
Tastensperre umschalten	23	-	Wie ein Druck auf die Lock-Taste. {"CMD":23}
Filterwechsel-Timer zurücksetzen	24	-	Setzt den Timer für den letzten Filterwechsel auf jetzt. {"CMD":24}
Wasserwechsel-Timer zurücksetzen	25	-	Setzt den Timer für den letzten Wasserwechsel auf jetzt. {"CMD":25}

Alle hier gelisteten Befehle gibt es in Firmware 1.2.0 und neuer. CMD 7 ist intern belegt und wird bewusst nicht ausgeführt.

Erweiterte Parameter für /hook/

Neben CMD und VALUE unterstützt der /hook/-Endpunkt optional weitere Parameter im JSON-Objekt:

Parameter	Typ	Beschreibung
XTIME	Integer	Unix-Timestamp, wann der Befehl ausgeführt werden soll. Standardmäßig sofort (jetzt).
INTERVAL	Integer	Wiederholungsintervall in Sekunden. 0 = einmalig.
FORCE	Boolean	true = Sicherheitsprüfungen umgehen (z.B. Pumpe ausschalten wenn Heizung läuft). Vorsichtig einsetzen.
TXT	String	Text, den das Pumpendisplay zusätzlich anzeigt (max. 96 Zeichen). Bei CMD 13 der Dateiname der Melodie.

Zusätzlich gelten feste Obergrenzen: XTIME maximal 4102444800 (01.01.2100), INTERVAL maximal 31622400 Sekunden (366 Tage), TXT maximal 96 Zeichen.

Gültige Wertebereiche

Seit Version 2.0.0 prüft das Modul jeden Webhook, bevor er in die Warteschlange kommt. Liegt ein Wert außerhalb des erlaubten Bereichs, wird der Befehl nicht ausgeführt und /hook/ antwortet mit 400 und einer Begründung im Klartext.

CMD	Erlaubte VALUE-Werte
0 Ziel-Temperatur	1-40 (wird als °C gelesen) oder 51-104 (wird als °F gelesen)
1, 2, 3, 4, 11, 18, 26	0/1 bzw. false/true
12 Display-Helligkeit	0-8
14 Umgebungstemperatur °F	-40 bis 140
15 Umgebungstemperatur °C	-40 bis 60
20 Fertig-Zeitpunkt	kein Wert, dafür muss XTIME gesetzt sein
27 pH-Wert	0-140 (entspricht pH 0,0-14,0)
28 Chlorgehalt	0-100 (entspricht 0,0-10,0 mg/L)
29 Cyanursäure	0-1000 (entspricht 0,0-100,0 mg/L)
30 Alkalität	0-300 mg/L

Antwortcodes von /hook/

Code	Bedeutung
200	Befehl angenommen. Der Antworttext enthält CMD VALUE XTIME des eingereihten Befehls
400	JSON fehlerhaft, unbekannter CMD oder Wert außerhalb des erlaubten Bereichs (Text nennt den Grund)
401	Webhook-Schutz ist aktiv, Zugangsdaten fehlen oder sind falsch
404	Webhooks sind am Modul deaktiviert
409	Warteschlange voll (maximal 20 Befehle)

Detaillierte Erklärungen zu den Parametern

• CMD (Command ID): Eine eindeutige Nummer, die den auszuführenden Befehl identifiziert (siehe Tabelle oben).
• VALUE (Wert): Der Wert, der für den jeweiligen Befehl gesetzt werden soll.
  • Boolean: Akzeptiert true (für einschalten/aktivieren) oder false (für ausschalten/deaktivieren).
  • Unsigned Integer: Akzeptiert positive Ganzzahlen (inkl. 0).
  • Integer: Akzeptiert positive und negative Ganzzahlen.

Anwendungsbeispiel mit curl

Du kannst Webhooks einfach über die Kommandozeile mit einem Tool wie curl testen. Um beispielsweise die Pumpe einzuschalten (angenommen, dein Modul ist unter 192.168.1.100 erreichbar):

curl "http://192.168.1.100/hook/?send={\"CMD\":4,\"VALUE\":true}"

Beachte die notwendige Maskierung der Anführungszeichen (\") innerhalb des JSON-Strings, wenn du curl in einer typischen Shell-Umgebung verwendest.

---

Statusabfrage per /getstates/

Seit Version 1.1.6 gibt es einen Endpunkt, mit dem du den aktuellen Ein-/Aus-Status aller wichtigen Komponenten deines WifiWhirl-Moduls auslesen kannst.

• Endpunkt: /getstates/
• Methode: HTTP GET
• Parameter: Keine

Antwortformat

Beispiel-Abfrage:

curl "http://192.168.1.100/getstates/"

Beispiel-Antwort:

{"pump":true,"heater":false,"bubbles":false,"jets":false,"power":true,"lock":true}

Bedeutung der Schlüssel:

Schlüssel	Typ	Beschreibung
pump	Boolean	Status der Filterpumpe (true = an, false = aus)
heater	Boolean	Status der Heizung (true = an, false = aus)
bubbles	Boolean	Status der AirJet-Düsen (true = an, false = aus)
jets	Boolean	Status der HydroJet-Düsen (true = an, false = aus)
power	Boolean	Gesamtstatus des Systems (true = an, false = aus)
lock	Boolean	Status der Tastensperre (true = aktiv, false = inaktiv)

---

Temperaturabfrage per /gettemps/

Seit Version 1.2.0 gibt es einen Endpunkt für alle Temperaturwerte. Die Antwort enthält immer beide Einheiten (Celsius und Fahrenheit), unabhängig von der Geräteeinstellung.

• Endpunkt: /gettemps/
• Methode: HTTP GET
• Parameter: Optional - Feldfilterung über Query-Parameter

Antwortformat

Beispiel-Abfrage (alle Felder):

curl "http://192.168.1.100/gettemps/"

Beispiel-Antwort:

{"currentC":38,"currentF":100,"targetC":40,"targetF":104,"ambientC":20,"ambientF":68,"unit":"C"}

Bedeutung der Schlüssel:

Schlüssel	Typ	Beschreibung
currentC	Number	Aktuelle Wassertemperatur in °C
currentF	Number	Aktuelle Wassertemperatur in °F
targetC	Number	Zieltemperatur in °C
targetF	Number	Zieltemperatur in °F
ambientC	Number	Umgebungstemperatur in °C
ambientF	Number	Umgebungstemperatur in °F
unit	String	Einstellung am Gerät: "C" (Celsius) oder "F" (Fahrenheit)

Feldfilterung

Um Bandbreite zu sparen, kannst du gezielt nur bestimmte Felder anfordern, indem du ihre Namen als Query-Parameter übergibst:

# Nur aktuelle Temperatur in Celsius
curl "http://192.168.1.100/gettemps/?currentC"

# Aktuelle und Zieltemperatur in Celsius
curl "http://192.168.1.100/gettemps/?currentC&targetC"

Ohne Parameter werden immer alle Felder zurückgegeben.

---

Webhooks aktivieren und absichern

Seit Version 2.0.0 kannst du die Webhook-Schnittstelle in der Weboberfläche unter Gerät → Webhooks steuern:

• Webhooks aktivieren: Schaltet /hook/ komplett ab, wenn du die Schnittstelle nicht brauchst. Aufrufe antworten dann mit 404. Auf ausgelieferten Modulen sind Webhooks aktiv.
• Webhooks schützen: Optionale HTTP-Basic-Auth mit eigenem Benutzernamen und Passwort - unabhängig vom Web-Login. Dieselben Zugangsdaten schützen auch den Prometheus-Endpunkt /metrics.

Mit aktiviertem Schutz sieht der Aufruf so aus:

curl -u benutzer:passwort "http://192.168.1.100/hook/?send={\"CMD\":4,\"VALUE\":true}"

Web-Login und Maschinen-Zugriff

Das allgemeine Web-Login (Gerät → Login) arbeitet mit Session-Cookies. Ist es aktiv, antworten /getstates/, /gettemps/, /getpolldata/ und /sendcommand/ für Skripte mit 401, weil diese keine Session haben. Für den Zugriff durch Maschinen bleiben /hook/ und /metrics erreichbar - sie nutzen die separate Webhook-Basic-Auth.

---

Prometheus-Metriken per /metrics

Für Monitoring-Setups liefert das Modul seine Kernwerte im Prometheus-Textformat.

• Endpunkt: /metrics
• Methode: HTTP GET
• Parameter: Keine
• Authentifizierung: dieselbe optionale Webhook-Basic-Auth (siehe oben)

curl "http://192.168.1.100/metrics"

Metrik	Bedeutung
layzspa_info{version,name}	Firmware-Version und Gerätename, Wert immer 1
layzspa_temperature_celcius	Aktuelle Wassertemperatur
layzspa_target_temperature_celcius	Zieltemperatur
layzspa_heater_state	Heizung (1 = an)
layzspa_pump_state	Filterpumpe (1 = an)
layzspa_jets_state	HydroJet-Düsen (1 = an)
layzspa_bubbles_state	AirJet-Düsen (1 = an)
layzspa_power_state	Gesamtstatus (1 = an)
layzspa_locked_state	Tastensperre (1 = aktiv)
layzspa_unit_state	Einheit am Gerät: 1 = °C, 0 = °F

Die beiden Temperaturmetriken kommen roh aus der Pumpe, also in der am Gerät eingestellten Einheit - trotz _celcius im Namen. layzspa_unit_state sagt dir, welche Einheit gerade gilt. Brauchst du beide Einheiten fest, nutze /gettemps/.

---

HTTP Polling Fallback

Seit Version 1.2.0 stehen zwei zusätzliche Endpunkte als Fallback für Browser bereit, die Probleme mit WebSocket-Verbindungen haben (z.B. bestimmte iOS-Safari-Versionen). Diese Endpunkte werden normalerweise vom Frontend intern genutzt und können in der Web-Konfiguration aktiviert werden.

GET /getpolldata/

Gibt den vollständigen aktuellen Gerätezustand als JSON-Array zurück (äquivalent zu den WebSocket-Nachrichten STATES, TIMES und OTHER).

• Endpunkt: /getpolldata/
• Methode: HTTP GET
• Parameter: Keine

POST /sendcommand/

Sendet einen Steuerbefehl an das Modul. Akzeptiert dasselbe JSON-Format wie die WebSocket-Schnittstelle.

• Endpunkt: /sendcommand/
• Methode: HTTP POST
• Body: JSON-Objekt mit den Feldern CMD, VALUE, XTIME, INTERVAL, TXT, FORCE

Beispiel:

curl -X POST "http://192.168.1.100/sendcommand/" \
     -H "Content-Type: application/json" \
     -d '{"CMD":4,"VALUE":true}'

---

Wichtige Sicherheitshinweise

• Standardmäßig keine Authentifizierung: Ohne aktivierten Webhook-Schutz kann jeder, der Zugriff auf dein lokales Netzwerk hat und die IP-Adresse/den Hostnamen deines Moduls kennt, diese Webhooks auslösen. Ab Version 2.0.0 kannst du das mit HTTP-Basic-Auth absichern (siehe Webhooks aktivieren und absichern).
• Keine Verschlüsselung: Das Modul spricht kein HTTPS. Zugangsdaten und Befehle gehen im Klartext über das Netzwerk.
• Netzwerksicherheit: Stelle sicher, dass dein WLAN angemessen gesichert ist (z.B. durch WPA2 Verschlüsselung und ein starkes Passwort).
• Kein Fernzugriff ohne VPN: Setze das Modul nicht direkt dem Internet aus (z.B. durch Port-Weiterleitungen im Router). Wenn du von außerhalb deines Heimnetzwerks auf die Webhooks zugreifen möchtest, verwende eine sichere VPN-Verbindung zu deinem Heimnetzwerk.

Bei Fragen oder Problemen mit den Webhooks, schaue bitte auch in die FAQ oder erstelle ein Issue im WifiWhirl GitHub Repository.