Diese Seite listet die IoT-Ereignisse auf, die ein Webhook abonnieren kann, sowie das data, das jedes davon enthält. Der Rahmen um data, die Header und die Signatur werden 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:
- Payloads enthalten nur IDs und unkritische 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-Deliveryund sortiere nach den Zeiten im Payload. - Die Beispiele zeigen nur das
eventund dasdatades Rahmens; der vollständige Rahmen enthält außerdemwebhookId,tenantIdundcreatedAt.
Geräte
| Ereignis | Gesendet wenn |
|---|---|
device.created | Ein Gerät wurde hinzugefügt: manuell, per Import, durch Provisionierung oder Beanspruchung oder als untergeordnetes Gerät eines Gateways |
device.updated | Der Name, das Label, der Typ, das Profil, das Gateway-Kennzeichen, die Zusatzinformationen oder der Status wurde geändert |
device.deleted | Ein Gerät wurde gelöscht (manuell, durch eine Freigabe oder durch Rückgängigmachen eines Imports) |
device.credentials_rotated | Der Zugang wurde rotiert, ersetzt, erneuert (X.509) oder widerrufen |
device.connected | Ein Gerät ist online gegangen und blieb für die Haltezeit online |
device.disconnected | Ein Gerät ist offline gegangen und blieb für die Haltezeit offline |
{ "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 untergeordnetes Gerät eines Gateways enthält zusätzlich 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 Felder (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-Präfix einer IPv4-Adresse bzw. das /48-Präfix 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, z. B. nach einer Zugangsänderung) oder quota (es hat ein Limit erreicht).
Haltezeit und Volumen. Eine Verbindungsänderung wird erst gesendet, nachdem sie die Haltezeit angehalten hat: Geräte > Einstellungen > Verbindungs-Webhooks: Haltezeit (Sekunden), Standard 30, 5 bis 3.600. Ein Gerät, das innerhalb dieser Zeit abbricht und zurückkehrt, sendet nichts. Standardmäßig werden pro Organisation höchstens 600 Verbindungsereignisse und 600 Geräteänderungsereignisse pro Minute gesendet; der Rest dieser Minute wird verworfen, und Ihre Inhaber und Administratoren erhalten einen Hinweis. Die Geräte bleiben über die API lesbar.
Alarme
| Ereignis | Gesendet wenn |
|---|---|
alarm.created | Ein Alarm wurde geöffnet (eine Profilregel, ein Flow-Block oder ein Bediener). Wird nicht gesendet, wenn ein offener Alarm erneut ausgelöst wird. |
alarm.acknowledged | Ein Bediener oder ein Flow hat einen offenen Alarm quittiert. Er bleibt offen. |
alarm.cleared | Ein 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 } } }urlist die Seite des Alarms in der App; stellen Sie Ihren Host und/tenant/<tenantId>davor.backfilled: truekennzeichnet einen Alarm, der durch verspätete Messwerte geöffnet wurde (z. B. nach dem Nachspielen des Puffers eines Gateways). Dafür wird niemand benachrichtigt.clearedByist"rule"oder{ "userId": "…" };reasonistclear,manualoderoriginator_deleted.metadataistnull, wenn eine Person den Alarm aufgelöst hat.- Eine Änderung der Schwere eines offenen Alarms sendet kein Webhook. Alarm-Webhooks werden nicht gedrosselt; das Ratenlimit Ihres Endpunkts gilt weiterhin.
Befehle
| Ereignis | Gesendet wenn |
|---|---|
rpc.completed | Ein Befehl endete mit SUCCESSFUL (beantwortet oder ein einseitiger Befehl wurde zugestellt) |
rpc.failed | Ein 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 im Payload enthalten: Lesen Sie sie mit GET /api/iot/rpc/{rpcId}. Ein abgebrochener Befehl sendet nichts.
Firmware
| Ereignis | Gesendet wenn |
|---|---|
ota.update.initiated | Einem Gerät wurde ein Firmware-Paket zur Installation bereitgestellt |
ota.update.succeeded | Ein Gerät läuft mit der Zielversion |
ota.update.failed | Das Update ist fehlgeschlagen, abgelaufen oder zurückgerollt |
ota.rollout.wave_completed | Eine Welle hat ihre Prüfschritte bestanden |
ota.rollout.paused | Ein Prüfschritt ist fehlgeschlagen oder eine Person hat den Rollout pausiert |
ota.rollout.resumed | Eine Person hat ihn fortgesetzt |
ota.rollout.completed | Die letzte Welle hat ihre Prüfschritte bestanden |
ota.rollout.aborted | Eine 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 Fehlercode 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-Payloads enthalten rolloutId, assignmentId, packageId, status, wave (ab 1), waves und at, dazu: updated, failures, successPct (Welle abgeschlossen); reason und die Zähler (pausiert; reason ist failure_gate, success_gate, no_result (kein Gerät hat abgeschlossen) oder manual); pausedReason (fortgesetzt); updated (abgeschlossen); reason (abgebrochen).
Provisionierung
| Ereignis | Gesendet wenn |
|---|---|
iot.device.claimed | Ein lizenziertes Gerät wurde in Ihre Organisation übernommen |
iot.device.released | Ein Gerät wurde in den Werkspool zurückgegeben: kind OWNER (Sie haben es freigegeben), FORCED (Plattform-Support) oder DEVICE (von der eigenen Seite des Geräts aus) |
{ "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
| Ereignis | Gesendet wenn |
|---|---|
rules.mode_changed | Ein Ort wurde in den manuellen Modus versetzt, kehrte in den Automatikmodus zurück oder sein manueller Modus endete von selbst |
rules.needs_attention | Eine Regel wurde deaktiviert, weil ein Gerät oder der darin genannte Ort 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. Eine Rückkehr in den Automatikmodus 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.succeededundesim.operation.failedgehören zur eSIM-Verwaltung, die sich in Entwicklung befindet.- API-Schlüssel-Ereignisse (
api_key.created,api_key.updated,api_key.rotated,api_key.deleted,api_key.expired) sowie Organisationsereignisse (Mitglieder, Einladungen, Abonnement) werden ebenfalls angeboten. Ihre Payloads sind auf dieser Seite nicht beschrieben.