JSON Webhook

Der JSON Webhook ermöglicht es, Sensordaten und Alarmmeldungen per HTTP POST an einen eigenen Webserver zu senden. So können Sie Aqua-Scope Geräte in beliebige Systeme integrieren – ohne MQTT-Broker, ohne Cloud-Abhängigkeit.

Bei jedem Mess- oder Alarmzyklus sendet das Gerät eine JSON-Nachricht an die konfigurierte URL. Optional kann der Server im HTTP-Response Steuerbefehle (Downlinks) an das Gerät zurücksenden.

Webhook aktivieren

Beim Erstsetup (Konfigurationsseite)

Während der WLAN-Einrichtung können Sie unter „Advanced" die Webhook-URL direkt eingeben.

Nachträglich über die App

Öffnen Sie die Aqua-Scope App
Wählen Sie das Gerät aus
Navigieren Sie zu Konfiguration → Kommunikationsoptionen
Tragen Sie die Webhook-URL und die gewünschten Optionen ein

Konfigurationsparameter

Parameter	Beschreibung
`url`	Ziel-URL des Webhooks (HTTPS empfohlen)
`enable`	Dienst aktivieren (`1`) oder deaktivieren (`0`)
`token`	Optionaler privater Token – wird als GET-Parameter an jeden Aufruf angehängt
`xxtea`	XXTEA-Verschlüsselung aktivieren (`1`) oder deaktivieren (`0`)
`raw`	Sensor-Rohdaten mit übertragen (`1`) oder nicht (`0`)

Beispiel JSON-Downlink zur Webhook-Konfiguration:

{
  "webs": {
    "enable": "1",
    "url": "https://mein-server.example.com/aqua-scope",
    "token": "mein-geheimer-token",
    "xxtea": 0,
    "raw": 0
  }
}

Sicherheitsoptionen

Token

Wenn ein Token konfiguriert ist, wird er als GET-Parameter an die URL angehängt. So kann der empfangende Server prüfen, ob die Anfrage von einem autorisierten Gerät stammt.

Beispiel: Bei URL https://mein-server.com/webhook und Token abc123 wird gesendet an:

https://mein-server.com/webhook?token=abc123

XXTEA-Verschlüsselung

Wenn XXTEA aktiviert ist, wird die JSON-Nachricht mit einem gerätespezifischen 128-Bit-Schlüssel verschlüsselt und als application/raw (Hexadezimal-kodiert) übertragen. Ohne Verschlüsselung wird application/json verwendet.

Der Schlüssel ist sicher im Gerät hinterlegt und kann nicht ausgelesen werden. Sie erhalten den Schlüssel auf Anfrage direkt von Aqua-Scope unter Angabe der 8-Byte Geräte-ID.

Nachrichtenformat

Alle Nachrichten werden per HTTP POST als JSON gesendet. Das Feld eid enthält die 8-stellige Geräte-ID.

Statusmeldung

Regelmäßiger Sensorbericht (Intervall konfigurierbar, Standard: 15 Min.):

{
  "eid": "12345678",
  "uptime": 12345,
  "temperature": 22.5,
  "pressure": 3200,
  "battery": 3.1
}

Die enthaltenen Felder variieren je nach Gerätetyp.

Alarmmeldung

{
  "eid": "12345678",
  "alarm": {
    "state": 1,
    "type": 6,
    "val": 1850,
    "source": 0,
    "map": 64
  }
}

Feld	Beschreibung
`state`	`1` = Alarm aktiv, `0` = Alarm beendet
`type`	Alarmtyp-ID (z.B. 1 = Flut, 6 = Überdruck, 8 = Unterdruck)
`val`	Aktueller Sensorwert, der den Alarm ausgelöst hat (z.B. Druck in mBar bei Unterdruck)
`source`	`0` = Hauptgerät, `≥1` = Untergerät (angelernter Flutsensor, Motor)
`map`	Kompletter Alarm-Vektor als Bitmap aller aktiven Alarme

Flow-Event (Durchflussereignis)

Wird bei Start und Ende einer Wasserentnahme gesendet (nur bei Geräten mit Verbrauchsmessung):

{
  "eid": "12345678",
  "flow": {
    "event": "2",
    "dur": 45,
    "cons": 3200
  }
}

Feld	Beschreibung
`event`	`1` = Entnahme gestartet, `2` = Entnahme beendet
`dur`	Dauer in Sekunden
`cons`	Verbrauch in Millilitern

Heartbeat

Periodische Lebenszeichen-Nachricht:

{
  "eid": "12345678",
  "uptime": 86400
}

Sensor-Rohdaten

Wenn raw: 1 konfiguriert ist, überträgt das Gerät zusätzlich die Rohdaten des Hauptsensors als hexadezimaler String (jeweils 4 Zeichen pro Messwert):

{
  "eid": "12345678",
  "arr": "035403560350034E0352..."
}

Beispiel: 0x0354 = 852, 0x0356 = 854, 0x0350 = 848

info

Rohdaten werden generell nicht verschlüsselt, auch wenn XXTEA aktiviert ist.

Downlink-Befehle (Server → Gerät)

Der Webhook-Server kann im HTTP-Response Steuerbefehle an das Gerät zurücksenden. Das Format entspricht dem Aqua-Scope Cloud Interface. Mehrere Befehle können in einem einzigen JSON-Objekt kombiniert werden.

`conf` – Konfiguration ändern

Ändert bis zu 32 Konfigurationsparameter gleichzeitig. Die Parameter werden in der angegebenen Reihenfolge verarbeitet.

{"conf": {"29": 600, "5": 8000}}

Welche Parameter verfügbar sind, steht im jeweiligen Produkthandbuch.

`valve` – Ventilsteuerung

Steuert alle angelernten Motoren gemeinsam.

{"valve": "0"}

Wert	Aktion
`"0"`	Ventil schließen
`"100"` (oder >0)	Ventil öffnen

`svalve` – Einzelnes Untergerät steuern

Steuert einen bestimmten Motor auf einem Sub-Device-Kanal.

{"svalve": {"c": 1, "s": 0}}

Feld	Beschreibung
`c`	Kommunikationskanal des Untergerätes
`s`	Ventilstatus: `0` = geschlossen, `>0` = offen

Bei batteriebetriebenen Untergeräten im Schlafmodus wird der Befehl beim nächsten Aufwachen ausgeführt.

`clear` – Alarm löschen

{"clear": 0}

Wert	Aktion
`0`	Alle aktiven Alarme löschen
`>0`	Bestimmten Alarmtyp löschen

info

Nach dem Löschen wird ein Alarm erst nach einem Neustart erneut ausgelöst, auch wenn die Ursache weiterhin besteht.

`system` – Systembefehle

{"system": 1}

Wert	Aktion
`1`	Gerät neustarten (Reboot)
`2`	Werksreset
`3`	Stummschalten – stoppt jegliche Kommunikation bis zum nächsten Einschalten

`list` – Konfiguration auslesen

{"list": 0}

Das Gerät antwortet mit einem Array aller Konfigurationsparameter:

{"list": [15, 1, 0, 4093, 0, 8000, 2000, ...]}

`sconf` – Untergerät konfigurieren

Setzt einen Konfigurationsparameter auf einem Untergerät.

{"sconf": {"c": 1, "p": 5, "v": 0x0107}}

Feld	Beschreibung
`c`	Kommunikationskanal des Untergerätes
`p`	Parameter-Index
`v`	Neuer Wert

`sub` – Untergeräte verwalten

Registriert, entfernt oder ändert Untergeräte (Motoren, Sensoren) über LoRa P2P.

Gerät registrieren:

{"sub": {"1": {"c": 1, "d": 1, "I": "0123456789ABCDEF", "k": "FEDCBA9876543210", "t": 1}}}

Feld	Beschreibung
`c`	Befehl: `1` = registrieren, `2` = entfernen, `3` = Typ ändern
`d`	Kanalzuordnung
`I`	16-stellige Geräte-ID (Dev EUI)
`k`	16-stelliger Kommunikationsschlüssel
`t`	Gerätetyp: `1` = Kugelhahn-Motor, `3` = Schrägsitzventil-Motor

`mqtt` – MQTT konfigurieren

Siehe MQTT-Anbindung.

{"mqtt": {"enable": "1", "server": "broker.example.com", "port": 1883, "login": "user", "password": "pass"}}

`webs` – Webhook konfigurieren

Siehe Webhook aktivieren.

`shell` – Shell-Befehl ausführen

Führt einen seriellen Konsolenbefehl auf dem Gerät aus. Leerzeichen werden als Unterstrich (_) kodiert.

{"shell": "AT+VER=?"}

`ota` – Firmware-Update

Startet ein Over-the-Air Firmware-Update.

{"ota": "TXN12345"}

Der Wert ist eine Transaktionsnummer, die das Gerät nutzt, um die Firmware vom OTA-Server anzufordern.

Empfangsbeispiel (PHP)

<?php
$json = json_decode(file_get_contents('php://input'), true);

if (!$json) {
    // XXTEA-verschlüsselt: entschlüsseln
    require_once 'xxtea-php.php';
    $key = hex2bin(DEVICE_KEY);
    $decrypted = xxtea_decrypt(
        base64_decode(file_get_contents('php://input')),
        $key
    );
    $json = json_decode($decrypted, true);
    if (!$json) die("Falscher Schlüssel oder falsche ID");
}

// Verarbeitung...
if (isset($json['alarm'])) {
    // Alarm behandeln
}

Unterstützte Geräte

Der JSON Webhook wird von allen WLAN-fähigen Aqua-Scope Geräten unterstützt:

AQMWIE01 – Ultraschall-Durchflussmesser
AQSWIE02 / AQXWIE02 – Leckageschutz-Monitor
RANWIE01 – Regenmesser
CLPWIE01 – Pipe Clip
KFRWIE01 – KFR-Motor (WLAN)
PREWIE02 – Drucksensor
MCLWIE01 – WLAN-Konnektor

Webhook aktivieren​

Beim Erstsetup (Konfigurationsseite)​

Nachträglich über die App​

Konfigurationsparameter​

Sicherheitsoptionen​

Token​

XXTEA-Verschlüsselung​

Nachrichtenformat​

Statusmeldung​

Alarmmeldung​

Flow-Event (Durchflussereignis)​

Heartbeat​

Sensor-Rohdaten​

Downlink-Befehle (Server → Gerät)​

conf – Konfiguration ändern​

valve – Ventilsteuerung​

svalve – Einzelnes Untergerät steuern​

clear – Alarm löschen​

system – Systembefehle​

list – Konfiguration auslesen​

sconf – Untergerät konfigurieren​

sub – Untergeräte verwalten​

mqtt – MQTT konfigurieren​

webs – Webhook konfigurieren​

shell – Shell-Befehl ausführen​

ota – Firmware-Update​

Empfangsbeispiel (PHP)​

Unterstützte Geräte​