Neu: Die KI-Firewall überwacht die gesamte Plattform und erklärt jeden Vorfall in einfachen Worten. So funktioniert es

Webhook event reference

Jedes IoT-Webhook-Ereignis – Geräte, Verbindungen, Alarme, Befehle, Firmware, Provisionierung, Regeln und Flows – mit Angabe, wann es gesendet wird, und einer Beispiel-Nutzlast.

Diese Seite listet die IoT-Ereignisse auf, die ein Webhook abonnieren kann, und die data, die jedes davon enthält. Die Hülle um data, die Header und die Signatur sind unter Webhooks beschrieben. Die Liste der Ereignisse, die Ihrer Organisation zur Verfügung stehen, ist außerdem über GET /api/webhooks/events abrufbar.

Allgemeine Regeln:

  • Nutzlasten enthalten nur IDs und unbedenkliche Felder. Ein Gerätezugang, Token, Passwort, Zertifikat oder Download-Link wird niemals gesendet.
  • Zeitangaben sind ISO-8601-Text in UTC, außer Alarmzeiten, die als Millisekunden seit der Epoche angegeben werden.
  • Ereignisse können außer der Reihenfolge eintreffen und selten doppelt. Dedupliziere anhand von X-Webhook-Delivery und sortiere nach den Zeiten in der Nutzlast.
  • Die Beispiele zeigen nur das event und die data der Hülle; die vollständige Hülle enthält außerdem webhookId, tenantId und createdAt.

Geräte

EreignisGesendet, wenn
device.createdEin Gerät wurde hinzugefügt: manuell, per Import, durch Provisionierung oder Beanspruchung oder als Kind-Gerät eines Gateways
device.updatedDer Name, das Label, der Typ, das Profil, das Gateway-Kennzeichen, die Zusatzinformationen oder der Status wurde geändert
device.deletedEin Gerät wurde gelöscht (manuell, durch eine Freigabe oder durch Rückgängigmachen eines Imports)
device.credentials_rotatedDer Zugang wurde rotiert, ersetzt, erneuert (X.509) oder widerrufen
device.connectedEin Gerät ist online gekommen und für die Haltezeit online geblieben
device.disconnectedEin Gerät ist offline gegangen und für die Haltezeit offline geblieben
{ "event": "device.created", "data": {
  "deviceId": "6f1c…", "name": "pump-station-04", "serial": null, "profileId": "a1b2…",
  "status": "ACTIVE", "isGateway": false, "createdAt": "2026-11-09T08:00:00.000Z" } }

Ein Kind-Gerät eines Gateways enthält außerdem gatewayDeviceId.

{ "event": "device.updated", "data": {
  "deviceId": "6f1c…", "name": "pump-station-04", "serial": null, "profileId": "a1b2…",
  "status": "DISABLED", "isGateway": false, "changedFields": ["status"], "previousStatus": "ACTIVE",
  "updatedAt": "2026-11-09T08:10:00.000Z" } }

changedFields nennt nur Feldnamen (sortiert: additionalInfo, isGateway, label, name, profileId, status, type), niemals deren Werte. previousStatus ist nur vorhanden, wenn sich der Status geändert hat. Eine Bearbeitung, die keines dieser Felder ändert, sendet nichts.

{ "event": "device.deleted", "data": {
  "deviceId": "6f1c…", "name": "pump-station-04", "serial": null, "profileId": "a1b2…",
  "credentialRevoked": true, "deletedAt": "2026-11-09T08:20:00.000Z" } }
{ "event": "device.credentials_rotated", "data": {
  "deviceId": "6f1c…", "name": "pump-station-04", "serial": null, "profileId": "a1b2…",
  "change": "rotated", "credentialType": "ACCESS_TOKEN", "previousType": "ACCESS_TOKEN",
  "changedAt": "2026-11-09T08:30:00.000Z" } }

change ist rotated, replaced, renewed oder revoked; nach revoked ist credentialType null.

{ "event": "device.connected", "data": {
  "deviceId": "6f1c…", "name": "router-17", "profileId": "a1b2…", "transport": "mqtts",
  "connectedAt": "2026-11-03T10:00:00.000Z", "remoteIpPrefix": "203.0.113.0/24" } }
{ "event": "device.disconnected", "data": {
  "deviceId": "6f1c…", "name": "router-17", "profileId": "a1b2…", "reason": "timeout",
  "disconnectedAt": "2026-11-03T12:00:00.000Z", "lastSeenAt": "2026-11-03T11:59:40.000Z", "onlineSeconds": 7200 } }

remoteIpPrefix ist das /24-Netz einer IPv4-Adresse oder das /48-Netz einer IPv6-Adresse, niemals die vollständige Adresse. reason ist clean (das Gerät hat sich getrennt), timeout (sein Keep-alive- oder Uplink-Fenster ist abgelaufen), kicked (der Server hat die Verbindung geschlossen, etwa nach einer Zugangsänderung) oder quota (es hat ein Limit erreicht).

Haltezeit und Volumen. Eine Verbindungsänderung wird erst gesendet, nachdem sie die Haltezeit überdauert hat: Geräte > Einstellungen > Verbindungs-Webhooks: Haltezeit (Sekunden), Standard 30, 5 bis 3.600. Ein Gerät, das innerhalb dieser Zeit ausfällt und zurückkehrt, sendet nichts. Standardmäßig werden pro Organisation und Minute höchstens 600 Verbindungsereignisse und 600 Geräteänderungsereignisse gesendet; der Rest dieser Minute wird verworfen, und Inhaber und Administratoren erhalten einen Hinweis. Die Geräte bleiben über die API lesbar.

Alarme

EreignisGesendet, wenn
alarm.createdEin Alarm wurde geöffnet (durch eine Profilregel, einen Flow-Block oder einen Bediener). Wird nicht gesendet, wenn ein offener Alarm erneut ausgelöst wird.
alarm.acknowledgedEin Bediener oder ein Flow hat einen offenen Alarm quittiert. Er bleibt offen.
alarm.clearedEin Alarm wurde aufgelöst: durch seine Regel oder seinen Flow, durch einen Bediener oder weil sein Gerät gelöscht wurde
{ "event": "alarm.created", "data": {
  "alarmId": "9a7e…", "type": "high_temperature", "severity": "CRITICAL",
  "originator": { "type": "DEVICE", "id": "6f1c…", "name": "cold-room-2" },
  "deviceId": "6f1c…", "profileId": "a1b2…", "url": "/admin/iot/alarms/9a7e…",
  "title": "Temperature too high", "startedAt": 1762678800000, "openedAt": 1762678800000,
  "details": { "temperature": 9.4 }, "backfilled": false, "metadata": { "topic": null } } }
{ "event": "alarm.acknowledged", "data": {
  "alarmId": "9a7e…", "type": "high_temperature", "severity": "CRITICAL", "originator": { "…": "…" },
  "deviceId": "6f1c…", "profileId": "a1b2…", "url": "/admin/iot/alarms/9a7e…",
  "ackBy": { "userId": "u-55…" }, "ackAt": 1762679100000 } }
{ "event": "alarm.cleared", "data": {
  "alarmId": "9a7e…", "type": "high_temperature", "severity": "CRITICAL", "originator": { "…": "…" },
  "deviceId": "6f1c…", "profileId": "a1b2…", "url": "/admin/iot/alarms/9a7e…",
  "clearedBy": "rule", "reason": "clear", "clearedAt": 1762680000000, "durationSeconds": 1200,
  "metadata": { "topic": null } } }
  • url ist die Seite des Alarms in der App; stellen Sie Ihren Host und /tenant/<tenantId> davor.
  • backfilled: true kennzeichnet einen Alarm, der durch verspätete Messwerte geöffnet wurde (etwa nachdem der Puffer eines Gateways erneut abgespielt wurde). Dafür wird niemand benachrichtigt.
  • clearedBy ist "rule" oder { "userId": "…" }; reason ist clear, manual oder originator_deleted. metadata ist null, wenn eine Person den Alarm aufgelöst hat.
  • Eine Änderung des Schweregrads eines offenen Alarms sendet keinen Webhook. Alarm-Webhooks unterliegen keiner Drosselung; das Ratenlimit Ihres Endpunkts gilt weiterhin.

Befehle

EreignisGesendet, wenn
rpc.completedEin Befehl endete mit SUCCESSFUL (beantwortet oder ein Befehl ohne Antwort wurde zugestellt)
rpc.failedEin Befehl endete mit FAILED, TIMEOUT (Ergebnis unbekannt) oder EXPIRED (hat das Gerät nie erreicht)
{ "event": "rpc.failed", "data": {
  "rpcId": "c0de…", "deviceId": "6f1c…", "method": "pump.start", "status": "TIMEOUT",
  "error": null, "source": "api", "completedAt": "2026-11-09T09:00:15.000Z" } }

Die Antwort selbst ist nicht in der Nutzlast enthalten: Lesen Sie sie mit GET /api/iot/rpc/{rpcId}. Ein abgebrochener Befehl sendet nichts.

Firmware

EreignisGesendet, wenn
ota.update.initiatedEinem Gerät wurde ein Firmware-Paket zur Installation bereitgestellt
ota.update.succeededEin Gerät läuft mit der Zielversion
ota.update.failedDas Update ist fehlgeschlagen, ist abgelaufen oder wurde zurückgerollt
ota.rollout.wave_completedEine Welle hat ihre Prüfschwellen bestanden
ota.rollout.pausedEine Prüfschwelle ist nicht erreicht worden oder eine Person hat den Rollout pausiert
ota.rollout.resumedEine Person hat ihn fortgesetzt
ota.rollout.completedDie letzte Welle hat ihre Prüfschwellen bestanden
ota.rollout.abortedEine Person hat ihn abgebrochen, seine Zuweisung wurde entfernt oder ersetzt, oder sein Paket wurde widerrufen
{ "event": "ota.update.failed", "data": {
  "deviceId": "6f1c…", "packageId": "f00d…", "title": "router-fw", "version": "2.5.0", "fromVersion": "2.4.1",
  "state": "FAILED", "attempts": 1, "at": "2026-11-09T10:00:00.000Z", "stage": "verify", "error": "…" } }

stage ist download, verify, update oder rollback; error ist der Code des Geräts oder ein Timeout.

{ "event": "ota.rollout.paused", "data": {
  "rolloutId": "r-12…", "assignmentId": "as-3…", "packageId": "f00d…", "status": "PAUSED", "wave": 2, "waves": 3,
  "at": "2026-11-09T11:00:00.000Z", "reason": "failure_gate", "failures": 4, "failurePct": 6.7, "successPct": 88.3 } }

Rollout-Nutzlasten enthalten rolloutId, assignmentId, packageId, status, wave (ab 1), waves und at, außerdem: updated, failures, successPct (Welle abgeschlossen); reason und die Zählwerte (pausiert; reason ist failure_gate, success_gate, no_result (kein Gerät hat abgeschlossen) oder manual); pausedReason (fortgesetzt); updated (abgeschlossen); reason (abgebrochen).

Provisionierung

EreignisGesendet, wenn
iot.device.claimedEin lizenziertes Gerät wurde in Ihre Organisation übernommen
iot.device.releasedEin Gerät wurde zurück in den Werkspool gegeben: kind OWNER (Sie haben es freigegeben), FORCED (Plattform-Support) oder DEVICE (von der eigenen Seite des Geräts)
{ "event": "iot.device.claimed", "data": {
  "deviceId": "6f1c…", "serial": "RT-0017", "model": "…", "claimedAt": "2026-11-09T07:00:00.000Z", "claimedByUserId": "u-55…" } }
{ "event": "iot.device.released", "data": {
  "deviceId": "6f1c…", "serial": "RT-0017", "model": "…", "kind": "OWNER", "releasedAt": "2026-11-09T07:30:00.000Z" } }

Regeln

EreignisGesendet, wenn
rules.mode_changedEin Ort wurde auf Manuell gesetzt, ist zurück auf Automatisch gewechselt oder sein manueller Modus ist von selbst abgelaufen
rules.needs_attentionEine Regel wurde ausgeschaltet, weil ein Gerät oder der Ort, den sie nennt, nicht mehr existiert
{ "event": "rules.mode_changed", "data": {
  "placeType": "asset", "placeId": "77aa…", "placeName": "Greenhouse 2", "mode": "manual", "change": "manual",
  "actorId": "u-55…", "until": 1762700000000, "reason": "Harvest" } }

change ist manual, auto oder expired; actorId ist null, wenn ein manueller Modus von selbst endete. Ein Wechsel zurück auf Automatisch enthält außerdem applyNow und rearmed.

{ "event": "rules.needs_attention", "data": {
  "ruleId": "ru-9…", "name": "Close vents at night", "reason": "…",
  "home": { "type": "asset", "id": "77aa…" } } }

Flows

automation.message wird nur durch einen Webhook-Block eines Flows gesendet, und nur an den einen Endpunkt, den der Block nennt (der „Automation message“ abonniert haben muss). Es enthält topic, payload, originator, flowId, flowVersion, nodeId, actor und die metadata-Schlüssel, die der Block auflistet, mit X-Idempotency-Key. Siehe Aktionsblöcke.

Weitere Ereignisse

  • esim.operation.succeeded und esim.operation.failed gehören zur eSIM-Verwaltung.
  • API-Schlüssel-Ereignisse (api_key.created, api_key.updated, api_key.rotated, api_key.deleted, api_key.expired) und Organisationsereignisse (Mitglieder, Einladungen, Abonnement) werden ebenfalls angeboten. Ihre Nutzlasten sind auf dieser Seite nicht beschrieben.