Skip to main content

JSON Webhook

The JSON Webhook allows you to send sensor data and alarm messages via HTTP POST to your own web server. This lets you integrate Aqua-Scope devices into any system — without an MQTT broker, without cloud dependency.

On each measurement or alarm cycle, the device sends a JSON message to the configured URL. Optionally, the server can send control commands (downlinks) back to the device in the HTTP response.

Enabling the Webhook​

During Initial Setup (Configuration Page)​

During the WiFi setup, you can enter the webhook URL directly under "Advanced".

Later via the App​

  1. Open the Aqua-Scope App
  2. Select the device
  3. Navigate to Configuration → Communication Options
  4. Enter the webhook URL and the desired options

Configuration Parameters​

ParameterDescription
urlTarget URL of the webhook (HTTPS recommended)
enableEnable (1) or disable (0) the service
tokenOptional private token — appended as a GET parameter to every request
xxteaEnable (1) or disable (0) XXTEA encryption
rawInclude (1) or exclude (0) raw sensor data

Example JSON downlink for webhook configuration:

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

Security Options​

Token​

When a token is configured, it is appended as a GET parameter to the URL. This allows the receiving server to verify that the request comes from an authorized device.

Example: With URL https://my-server.com/webhook and token abc123, the request is sent to:

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

XXTEA Encryption​

When XXTEA is enabled, the JSON message is encrypted with a device-specific 128-bit key and transmitted as application/raw (hex-encoded). Without encryption, application/json is used.

The key is securely stored on the device and cannot be read out. You can obtain the key upon request directly from Aqua-Scope by providing the 8-byte device ID.

Message Format​

All messages are sent via HTTP POST as JSON. The eid field contains the 8-character device ID.

Status Message​

Regular sensor report (interval configurable, default: 15 min.):

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

The included fields vary depending on the device type.

Alarm Message​

{
  "eid": "12345678",
  "alarm": {
    "state": 1,
    "type": 6,
    "val": 1850,
    "source": 0,
    "map": 64
  }
}
FieldDescription
state1 = alarm active, 0 = alarm cleared
typeAlarm type ID (e.g., 1 = flood, 6 = overpressure, 8 = underpressure)
valCurrent sensor value that triggered the alarm (e.g., pressure in mBar for underpressure)
source0 = main device, ≥1 = sub-device (paired flood sensor, motor)
mapComplete alarm vector as a bitmap of all active alarms

Flow Event​

Sent at the start and end of a water draw (only for devices with consumption metering):

{
  "eid": "12345678",
  "flow": {
    "event": "2",
    "dur": 45,
    "cons": 3200
  }
}
FieldDescription
event1 = draw started, 2 = draw ended
durDuration in seconds
consConsumption in milliliters

Heartbeat​

Periodic keep-alive message:

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

Raw Sensor Data​

When raw: 1 is configured, the device additionally transmits the main sensor's raw data as a hexadecimal string (4 characters per measurement value):

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

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

info

Raw data is generally not encrypted, even when XXTEA is enabled.

Downlink Commands (Server → Device)​

The webhook server can send control commands back to the device in the HTTP response. The format corresponds to the Aqua-Scope Cloud Interface. Multiple commands can be combined in a single JSON object.

conf — Change Configuration​

Changes up to 32 configuration parameters simultaneously. Parameters are processed in the specified order.

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

Which parameters are available is documented in the respective product manual.

valve — Valve Control​

Controls all paired motors together.

{"valve": "0"}
ValueAction
"0"Close valve
"100" (or >0)Open valve

svalve — Control Individual Sub-Device​

Controls a specific motor on a sub-device channel.

{"svalve": {"c": 1, "s": 0}}
FieldDescription
cCommunication channel of the sub-device
sValve status: 0 = closed, >0 = open

For battery-powered sub-devices in sleep mode, the command is executed on the next wake-up.

clear — Clear Alarm​

{"clear": 0}
ValueAction
0Clear all active alarms
>0Clear a specific alarm type
info

After clearing, an alarm will only be triggered again after a restart, even if the cause persists.

system — System Commands​

{"system": 1}
ValueAction
1Reboot device
2Factory reset
3Mute — stops all communication until the next power-on

list — Read Configuration​

{"list": 0}

The device responds with an array of all configuration parameters:

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

sconf — Configure Sub-Device​

Sets a configuration parameter on a sub-device.

{"sconf": {"c": 1, "p": 5, "v": 0x0107}}
FieldDescription
cCommunication channel of the sub-device
pParameter index
vNew value

sub — Manage Sub-Devices​

Registers, removes, or modifies sub-devices (motors, sensors) via LoRa P2P.

Register device:

{"sub": {"1": {"c": 1, "d": 1, "I": "0123456789ABCDEF", "k": "FEDCBA9876543210", "t": 1}}}
FieldDescription
cCommand: 1 = register, 2 = remove, 3 = change type
dChannel assignment
I16-character device ID (Dev EUI)
k16-character communication key
tDevice type: 1 = ball valve motor, 3 = angle seat valve motor

mqtt — Configure MQTT​

See MQTT Integration.

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

webs — Configure Webhook​

See Enabling the Webhook.

shell — Execute Shell Command​

Executes a serial console command on the device. Spaces are encoded as underscores (_).

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

ota — Firmware Update​

Starts an over-the-air firmware update.

{"ota": "TXN12345"}

The value is a transaction number used by the device to request the firmware from the OTA server.

Receiving Example (PHP)​

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

if (!$json) {
    // XXTEA-encrypted: decrypt
    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("Wrong key or wrong ID");
}

// Processing...
if (isset($json['alarm'])) {
    // Handle alarm
}

Supported Devices​

The JSON Webhook is supported by all WiFi-enabled Aqua-Scope devices: