Ingest-API und Alarm-Webhooks

Sensorwerte per Ingest-API an ProbeHarbor senden (natives JSON, SenML oder Home Assistant REST) und Alarme an Discord, IFTTT oder Home Assistant schicken.

Nahaufnahme weißer Cat-5e-Ethernet-Kabel mit RJ45-Steckern
Das Fühler-JSON verlässt das LAN meist über Ethernet oder ein nahes Relay, nicht direkt übers öffentliche Internet. Foto: DiscDepotDundee.co.uk. CC BY-SA 4.0

Neben dem Abrufen von HTTPS-JSON-Feeds nimmt ProbeHarbor Push-Daten von ESP32-, Pico-W- oder Arduino-Geräten an und kann Alarmbenachrichtigungen an Discord, SMS, Web-Push und generische HTTPS-Webhooks für IFTTT oder Home Assistant verteilen. Eine Übersicht der Endpunkte und den OpenAPI-Download findest du in der HTTP-API-Referenz.

Push-Ingest

Lege unter Dashboard → Devices ein Push-Gerät an und kopiere den Ingest-Schlüssel aus dem Hinweis (30 Minuten, übersteht ein Neuladen). Sensoren werden beim ersten POST automatisch importiert; die manuelle Zuordnung unter Advanced ist optional. Komplette Anleitung: Push- und Pull-Geräte hinzufügen. Sende Messwerte so:

POST /api/ingest/<device-key>
Content-Type: application/json

Klassisches Arduino-JSON

{
  "temp": {
    "0": { "c": 18.5, "f": 65.3, "h": 42 },
    "1": { "c": 19.0, "f": 66.2, "h": 40 }
  }
}

Typisierter Multisensor-Payload

{
  "sensors": [
    { "key": "garage_temp", "kind": "temperature", "value": 65.3, "unit": "F" },
    { "key": "garage_rh", "kind": "humidity", "value": 42, "unit": "%" },
    { "key": "door1", "kind": "door", "bool": true },
    { "key": "co2", "kind": "co2", "value": 820, "unit": "ppm" },
    { "key": "pm25", "kind": "pm25", "value": 12, "unit": "µg/m³" },
    { "key": "sump", "kind": "level", "value": 22, "unit": "%" }
  ],
  "battery": 87,
  "rssi": -62
}

Unterstützte Typen: temperature, humidity, co2, pressure, pm25, voc, level, energy, door, power, flood, motion, generic. Optionale Felder auf oberster Ebene, battery / battery_pct und rssi, aktualisieren die Zustandsdaten des Geräts. Beispiel-Sketches in CircuitPython, MicroPython, Arduino, Zephyr C, WCHNET C und GNU-AVR-Assembler für DS18B20 / MAX31855 / MAX6675 sowie Uno + W5100 (ethernet_dht22_ingest, klassisches temp-JSON): sketches/. Das Ethernet-Shield kann kein TLS: Kombiniere es mit push_https_forward.py auf einem Rechner im LAN.

SenML (RFC 8428)

Wenn deine Firmware oder dein Gateway bereits SenML-JSON veröffentlicht, sende das Array direkt per POST, ohne umschließendes Objekt. ProbeHarbor erkennt SenML automatisch, wenn die nativen Formate temp / sensors[] fehlen. Temperatur nutzt die Einheit Cel oder degF, Luftfeuchte %RH. Die Fühlerschlüssel stammen aus dem SenML-Namen (letztes Pfadsegment).

[
  { "bn": "probeharbor/garage/", "n": "0", "u": "Cel", "v": 18.5 },
  { "n": "0", "u": "%RH", "v": 42 },
  { "n": "door", "vb": true }
]

Live-Beispiel: Beispiel-SenML-Feed. Pull-Feeds akzeptieren dasselbe Array, wenn der konfigurierte JSON-Stamm fehlt.

REST-Sensor-JSON von Home Assistant

Die Antwort eines einzelnen REST-Sensors (state plus attributes.unit_of_measurement) wird bei Push-Ingest und Pull-Feeds ebenfalls automatisch erkannt. Ordne auf Devices den Fühlerschlüssel state zu (oder bei Payloads mit mehreren Entitäten das Entitätssuffix).

{
  "state": "65.3",
  "attributes": {
    "unit_of_measurement": "°F",
    "friendly_name": "Garage temperature"
  }
}

Live-Beispiel: Beispiel-HA-REST-Feed. Für die vollständige HA-Einrichtung (HACS, MQTT-Bridge, Innenreferenz) siehe die Home-Assistant-Integration.

Ausgehende Alarm-Webhooks

Pro-Konten können in den Alarmeinstellungen einen ausgehenden Webhook aktivieren. Jeder Alarm sendet dieses JSON per POST:

{
  "title": "Garage temperature alert",
  "body": "Probe 1 is 31.2°F …",
  "kind": "threshold",
  "sent_at": "2026-08-25T12:00:00.000Z"
}

kind kann threshold, rate, outage, forecast, rule, digest oder generic sein. Ist ein Webhook-Secret gesetzt, enthält die Anfrage X-Signature als hexadezimalen HMAC-SHA256 des Roh-Bodys. Nutze ihn in Home Assistant oder IFTTT Webhooks, um die Echtheit zu prüfen.

Home Assistant

Installiere die offizielle HACS-Integration für Sensoren aus Freigabelinks und Dienste zum Stummschalten/für den Urlaubsmodus. Für Alarme in HA nutzt du den ausgehenden HTTPS-Webhook (Pro) oder importierst den Blueprint. Für MQTT-Messwerte in ProbeHarbor siehe das MQTT-Bridge-Rezept.

HA-Blueprint herunterladen (YAML)

automation:
  - alias: ProbeHarbor webhook
    trigger:
      - platform: webhook
        webhook_id: probeharbor_alerts
        allowed_methods:
          - POST
        local_only: false
    action:
      - service: notify.persistent_notification
        data:
          title: "{{ trigger.json.title }}"
          message: "{{ trigger.json.body }}"

Richte die URL deines ausgehenden ProbeHarbor-Webhooks auf https://<your-ha-host>/api/webhook/probeharbor_alerts (oder eine Cloudflare-Tunnel- bzw. Nabu-Casa-URL). Prüfe X-Signature in einer Template-Bedingung, wenn du ein Secret gesetzt hast.

Für MQTT lässt du Home Assistant (oder Node-RED) den Webhook empfangen und an deinen Broker veröffentlichen – so bleibt MQTT lokal, während ProbeHarbor bei HTTPS bleibt. Der Blueprint enthält dafür eine optionale Eingabe für das MQTT-Topic.

Grafana-/Prometheus-Metriken

Pro-Konten können Dashboard-API-Schlüssel anlegen (Dashboard → Share) und Folgendes abfragen:

GET /api/v1/metrics
Authorization: Bearer gtm_…

Oder nutze einen Pro-Freigabelink mit dem Bereich Metrics:

GET /api/share/<token>/readings?format=prometheus

Oder ?format=grafana für ein einfaches JSON-Array mit Datenpunkten. Der Freigabebereich für den Verlauf liefert ein 7-Tage-Diagramm auf der öffentlichen Seite.

Alarmkanäle

  • E-Mail und Discord (alle Tarife)
  • Telegram-Bot-Token + Chat-ID (deine Zugangsdaten)
  • Slack-Incoming-Webhook-URL (deine Zugangsdaten)
  • Browser- und Android-Push (jeder Tarif)
  • Twilio-SMS, ausgehender Webhook (Pro)

Alarme unterstützen außerdem prognostiziertes Frostrisiko, Ruhezeiten und kombinierte UND-Regeln (zum Beispiel Tor offen + Temperaturabfall). Siehe Dashboard → Alerts.

E-Mail-Alarme bleiben in allen Tarifen verfügbar. Wöchentliche Zusammenfassungen lassen sich unabhängig von Frost- und Luftfeuchte-Schwellenalarmen aktivieren. Freiwillig geteilte Städtewerte erscheinen unter /freeze-map.

Verwandte Anleitungen

Häufige Fragen

Braucht der Arduino eine öffentliche IP-Adresse?
Nein. Push-Ingest sendet ausgehend mit einem Geräteschlüssel an ProbeHarbor. Pull-Feeds brauchen eine erreichbare HTTPS-JSON-URL, falls du stattdessen diesen Weg nutzt.

Was gehört in eine Ingest-Payload?
Temperatur (und Luftfeuchtigkeit) nach Fühler-Index, dazu optional Tür- und Stromfelder, Akkustand und RSSI. Native Formen sind flache Schlüssel, ein temp-Objekt oder sensors[]. SenML-Arrays (RFC 8428) und das REST-Status-JSON von Home Assistant werden ebenfalls automatisch erkannt. Halte die Schlüssel stabil, damit die Zuordnungen im Dashboard gültig bleiben.