So integrieren Sie SoilSense-Bodenfeuchtedaten mit unserer API und Webhooks

Die meisten Bodenfeuchte-Sensorsysteme sind ein geschlossenes System: Ihre Daten kommen hinein, aber sie für die eigenen Werkzeuge wieder herauszuholen, wird zur Nebensache. SoilSense sieht das umgekehrt. SoilSense bietet eine benutzerfreundliche REST-API und Webhooks in Echtzeit, sodass Ihre Bodenfeuchtedaten in jedes System fließen können, das Sie bereits betreiben — Farm-Management-Software, BI-Dashboards, Bewässerungssteuerungen oder eine einfache Tabellenkalkulation.

Dieser Leitfaden zeigt, wie Sie SoilSense mit Ihren eigenen Systemen verbinden, mit praktischen Beispielen sowohl für das Abrufen von Daten auf Anfrage als auch für das Zusenden in dem Moment, in dem sie eintreffen.

Worauf Sie zugreifen können

Wenn Ihre Daten offen sind, werden die Messwerte Ihrer Sensoren zu Bausteinen, die Sie überall verwenden können. Über die API lesen Sie:

• Volumetrischer Wassergehalt (Bodenfeuchte) in jeder Sensortiefe
• Bodentemperatur und Salinität
• Pflanzenverfügbares Wasser (PAW) — der Wert, der Ihnen tatsächlich sagt, wann Sie bewässern sollten
• Niederschlag von angeschlossenen Regenmessern
• Ihren Betrieb und Ihre Beobachtungsstandorte, deren Konfiguration und die gesamte Messhistorie
• Den neuesten Messwert für jeden Standort, für Statusprüfungen in Echtzeit

Es sind dieselben Daten, die Sie im SoilSense-Dashboard sehen, programmatisch verfügbar.

Schritt 1: Erstellen Sie einen API-Schlüssel

Die API verwendet eine einfache Authentifizierung per API-Schlüssel. Erstellen Sie einen Schlüssel in den Einstellungen Ihres SoilSense-Kontos und behandeln Sie ihn wie ein Passwort — halten Sie ihn geheim und aus clientseitigem Code sowie öffentlichen Repositories heraus.

Jede Anfrage trägt den Schlüssel in einem x-api-key-Header. Das ist die gesamte Authentifizierung: kein OAuth-Tanz, keine Tokens, die erneuert werden müssen.

Schritt 2: Ihre erste Anfrage

Mit einem Schlüssel in der Hand ist eine Anfrage eine einzige Zeile. Hier mit curl, um die Details Ihres Betriebs abzurufen:

curl https://api.app.soilsense.io/api/farm \
  -H "x-api-key: $SOILSENSE_API_KEY"

Derselbe Aufruf aus JavaScript:

const res = await fetch("https://api.app.soilsense.io/api/farm", {
  headers: { "x-api-key": process.env.SOILSENSE_API_KEY },
});

const farm = await res.json();
console.log(farm);

Jeder Endpunkt folgt genau dieser Form — nur der Pfad ändert sich. GET /api/farm/sites listet Ihre Beobachtungsstandorte und deren IDs auf; von dort liefert GET /api/site/{siteId}/observations/latest den neuesten Messwert, /observations die vollständige Historie und /precipitation die Daten angeschlossener Regenmesser. Die API-Referenz dokumentiert jeden Endpunkt mit seinen genauen Parametern.

Schritt 3: Arbeiten Sie mit den Daten

Die Antworten kommen als sauberes JSON zurück, sodass Sie sie direkt in das einbauen können, was Sie gerade entwickeln. Eine Antwort mit dem neuesten Messwert sieht ungefähr so aus:

{
  "timestamp": 1640995200000,
  "rssi": -75,
  "data": {
    "top": {
      "volumetricWaterContent": 25.5,
      "temperature": 18.5,
      "plantAvailableWater": 75.2,
      "salinity": 0.45
    }
  }
}

Die Messwerte sind nach Sensortiefe gruppiert (top, mid, midBot, bot), mit timestamp in Millisekunden seit der Epoch und Feuchtewerten in Prozent. Ab hier ist es gewöhnlicher Code. Hängen Sie die Zeile an eine Datenbank an, posten Sie sie in einen Slack-Kanal, wenn PAW unter einen Schwellenwert fällt, schreiben Sie sie in ein Google Sheet oder leiten Sie sie an Ihre Bewässerungssteuerung weiter. Und da auch die vollständige Historie verfügbar ist, können Sie ein Dashboard rückwirkend befüllen oder alles jederzeit in ein Data Warehouse exportieren — Ihre Daten sind nie eingesperrt.

Lassen Sie sich Daten per Webhook zusenden

Die API in festen Abständen abzufragen funktioniert, ist für Echtzeit-Integrationen aber Verschwendung. Webhooks drehen das Modell um: Statt dass Sie um Daten bitten, sendet SoilSense sie an einen Endpunkt, den Sie kontrollieren, in dem Moment, in dem etwas passiert. Es gibt zwei Arten.

Telemetrie-Webhooks liefern neue Sensormesswerte, sobald sie eintreffen — die richtige Wahl für Echtzeit-Dashboards, automatische Bewässerung und Benachrichtigungen.

Attribut-Webhooks werden ausgelöst, wenn ein Beobachtungsstandort angelegt oder geändert wird, sodass Ihre eigenen Aufzeichnungen synchron bleiben, ohne dass jemand etwas neu eintippen muss.

Sie hinterlegen eine einzige Webhook-URL in den Geräteeinstellungen; SoilSense hängt /telemetry und /attributes an, sodass Sie für jede eine Route bereitstellen. Jedes Ereignis trifft als HTTP-POST mit einem JSON-Body ein. Ein Telemetrie-Payload trägt einen Zeitstempel und einen flachen Satz von Werten:

{
  "ts": 1640995200000,
  "values": {
    "volumetricWaterContent_top": 25.5,
    "plantAvailableWater_top": 75.2,
    "irrigationStatus": "ok"
  }
}

Ihn zu verarbeiten ist so einfach wie jede andere Route:

app.post("/telemetry", (req, res) => {
  const { ts, values } = req.body;
  // z. B. Messwert speichern, Dashboard aktualisieren, Bewässerung auslösen
  saveReading(ts, values);
  res.sendStatus(200);
});

Prüfen, ob Webhooks echt sind

Da ein Webhook-Endpunkt eine öffentliche URL ist, sollten Sie bestätigen, dass jede Anfrage wirklich von SoilSense stammt. Wenn Sie ein Secret für Ihren Webhook festlegen, signiert SoilSense jede Anfrage mit HMAC-SHA256 und sendet die Signatur in einem SoilSense-Signature-Header im Format t=<unix_ms>,v1=<hex_hmac>. SoilSense signiert den Zeitstempel und den rohen Request-Body, verbunden mit einem Punkt — <t>.<rawBody> — sodass Sie denselben HMAC auf Ihrer Seite neu berechnen und vergleichen:

import crypto from "node:crypto";

// SoilSense-Signature: t=<unix_ms>,v1=<hex_hmac>
function isFromSoilSense(rawBody, signatureHeader, secret) {
  const parts = Object.fromEntries(
    signatureHeader.split(",").map((kv) => kv.split("=")),
  );

  // SoilSense signiert Zeitstempel und Rohtext des Bodys, verbunden mit einem Punkt.
  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${parts.t}.${rawBody}`)
    .digest("hex");

  const received = Buffer.from(parts.v1, "hex");
  const computed = Buffer.from(expected, "hex");
  return (
    received.length === computed.length &&
    crypto.timingSafeEqual(received, computed)
  );
}

Zwei Details sind wichtig. Prüfen Sie gegen den rohen Request-Body — die exakten Bytes, die SoilSense gesendet hat, bevor ein JSON-Parser sie neu serialisiert — sonst stimmen die Hashes nicht überein. Und verwenden Sie einen zeitkonstanten Vergleich (wie oben), damit die Prüfung selbst keine Informationen preisgibt. Für zusätzliche Sicherheit gegen Replays weisen Sie jede Anfrage ab, deren t-Zeitstempel älter als ein paar Minuten ist.

Was Sie bauen können

Ein wenig Klebe-Code verbindet Bodenfeuchtedaten mit dem Rest Ihres Betriebs:

• Farm-Management-Software — bringen Sie Bodenfeuchte und pflanzenverfügbares Wasser in die Plattform, in der Sie die Bewässerung ohnehin planen.
• Automatische Bewässerung — starten, stoppen oder justieren Sie Steuerungen anhand von Echtzeitmesswerten und Austrocknungswarnungen.
• BI und Reporting — speisen Sie Dashboards, Tabellen und Berichte für die Wasserbilanz und die Compliance.
• Eigene Benachrichtigungen — leiten Sie Messwerte in Ihre eigene Benachrichtigungs-, Automatisierungs- oder Analyse-Pipeline.

Sicherheit und Ratenbegrenzungen

Eine kurze Checkliste, bevor Sie eine Integration ausliefern:

• Halten Sie Ihren API-Schlüssel serverseitig und außerhalb der Versionskontrolle.
• Prüfen Sie Webhook-Signaturen mit HMAC-SHA256 und weisen Sie alles ab, was die Prüfung nicht besteht.
• Die API wendet Ratenbegrenzungen pro Schlüssel an — 20 Anfragen pro Sekunde, 600 pro Minute und 10.000 pro Stunde, gemeinsam durchgesetzt. Jede Antwort enthält die Header RateLimit-Remaining und RateLimit-Reset, und eine Überschreitung liefert einen 429. Bündeln Sie historische Abrufe in Batches und setzen Sie für alles, was in Echtzeit sein muss, auf Webhooks.

Legen Sie los

Offene Daten sind der Unterschied zwischen einem Sensor, den Sie einmal am Tag ablesen, und einem System, das im Hintergrund die Werkzeuge antreibt, auf die Sie sich ohnehin verlassen. Wenn Sie SoilSense mit Ihrem eigenen Stack verbinden möchten, ist alles bereit, was Sie brauchen:

• Lesen Sie die vollständige Übersicht zu API und Webhooks
• Tauchen Sie in die API-Referenz und die Beispiele ein

Haben Sie eine bestimmte Integration im Sinn? Nehmen Sie Kontakt auf — wir helfen Ihnen gern, das Beste aus der API und den Webhooks herauszuholen.