Yeni: Yapay zekâ güvenlik duvarı tüm platformu izliyor ve her olayı sade bir dille açıklıyor. Nasıl çalıştığını görün

Webhook olay referansı

Tüm IoT webhook olayları – cihazlar, bağlantılar, alarmlar, komutlar, firmware, provisioning, kurallar ve flow'lar – ne zaman gönderildikleri ve örnek bir payload ile.

Bu sayfa, bir webhook’un abone olabileceği IoT olaylarını ve her birinin taşıdığı data alanını listeler. data etrafındaki zarf, başlıklar ve imza Webhooks sayfasında açıklanmıştır. Kuruluşunuza sunulan olayların listesine GET /api/webhooks/events ile de ulaşabilirsiniz.

Genel kurallar:

  • Payload’lar yalnızca kimlikleri ve güvenli alanları taşır. Cihaz kimlik bilgisi, token, parola, sertifika veya indirme bağlantısı asla gönderilmez.
  • Zamanlar UTC cinsinden ISO 8601 metnidir; alarm zamanları ise epoch’tan bu yana geçen milisaniyedir.
  • Olaylar sırasız ve nadiren iki kez gelebilir. X-Webhook-Delivery üzerinden tekilleştirin ve payload’daki zamanlara göre sıralayın.
  • Örneklerde yalnızca zarfın event ve data alanları gösterilir; tam zarfta ayrıca webhookId, tenantId ve createdAt bulunur.

Cihazlar

OlayGönderildiği an
device.createdBir cihaz eklendi: elle, içe aktarmayla, provisioning veya claiming ile ya da bir gateway’in alt cihazı olarak
device.updatedAd, etiket, tür, profil, gateway işareti, ek bilgi veya durum değişti
device.deletedBir cihaz silindi (elle, bir release ile veya içe aktarma geri alınarak)
device.credentials_rotatedKimlik bilgisi döndürüldü, değiştirildi, yenilendi (X.509) veya iptal edildi
device.connectedBir cihaz çevrimiçi oldu ve bekleme süresi boyunca çevrimiçi kaldı
device.disconnectedBir cihaz çevrimdışı oldu ve bekleme süresi boyunca çevrimdışı kaldı
{ "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" } }

Bir gateway’in alt cihazı ayrıca gatewayDeviceId taşır.

{ "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 yalnızca alan adlarını belirtir (sıralı: additionalInfo, isGateway, label, name, profileId, status, type), değerlerini asla. previousStatus yalnızca durum değiştiğinde bulunur. Bu alanların hiçbirini değiştirmeyen bir düzenleme hiçbir şey göndermez.

{ "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 değeri rotated, replaced, renewed veya revoked olur; revoked sonrasında credentialType değeri null olur.

{ "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, bir IPv4 adresinin /24 önekidir ya da bir IPv6 adresinin /48 önekidir; tam adres asla verilmez. reason değeri clean (cihaz bağlantıyı kesti), timeout (keep-alive veya uplink penceresi doldu), kicked (sunucu bağlantıyı kapattı, örneğin kimlik bilgisi değişiminden sonra) veya quota (bir sınıra ulaştı) olur.

Bekleme süresi ve hacim. Bağlantı değişikliği yalnızca bekleme süresi boyunca sürdükten sonra gönderilir: Devices > ayarlar > Connection webhooks: hold time (seconds), varsayılan 30, 5 ile 3.600 arası. Bu süre içinde kopup geri gelen bir cihaz hiçbir şey göndermez. Varsayılan olarak kuruluş başına dakikada en fazla 600 bağlantı olayı ve 600 cihaz değişikliği olayı gönderilir; o dakikanın geri kalanı atılır ve sahipleriniz ile yöneticileriniz bir bildirim alır. Cihazlar API üzerinden okunabilir kalır.

Alarmlar

OlayGönderildiği an
alarm.createdBir alarm açıldı (profil kuralı, flow bloğu veya bir operatör tarafından). Açık bir alarm yeniden tetiklendiğinde gönderilmez.
alarm.acknowledgedBir operatör veya bir flow, açık bir alarmı onayladı. Alarm açık kalır.
alarm.clearedBir alarm çözüldü: kuralı veya flow’u tarafından, bir operatör tarafından ya da cihazı silindiği için
{ "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, alarmın uygulamadaki sayfasıdır; önüne kendi host’unuzu ve /tenant/<tenantId> ekleyin.
  • backfilled: true, geç gelen okumalarla açılan bir alarmı belirtir (örneğin bir gateway’in tamponu yeniden oynatıldıktan sonra). Bunlar için kimseye bildirim gitmez.
  • clearedBy değeri "rule" veya { "userId": "…" } olur; reason değeri clear, manual veya originator_deleted olur. Alarmı bir kişi temizlediğinde metadata değeri null olur.
  • Açık bir alarmın önem derecesindeki değişiklik webhook göndermez. Alarm webhook’ları kısıtlanmaz; endpoint’inizin hız sınırı yine de geçerlidir.

Komutlar

OlayGönderildiği an
rpc.completedBir komut SUCCESSFUL olarak sona erdi (yanıtlandı veya tek yönlü komut teslim edildi)
rpc.failedBir komut FAILED, TIMEOUT (sonuç bilinmiyor) veya EXPIRED (cihaza hiç ulaşmadı) olarak sona erdi
{ "event": "rpc.failed", "data": {
  "rpcId": "c0de…", "deviceId": "6f1c…", "method": "pump.start", "status": "TIMEOUT",
  "error": null, "source": "api", "completedAt": "2026-11-09T09:00:15.000Z" } }

Yanıtın kendisi payload’da yoktur: GET /api/iot/rpc/{rpcId} ile okuyun. İptal edilen bir komut hiçbir şey göndermez.

Firmware

OlayGönderildiği an
ota.update.initiatedBir cihaza kurulması için firmware paketi verildi
ota.update.succeededBir cihaz hedef sürümü çalıştırıyor
ota.update.failedGüncelleme başarısız oldu, zaman aşımına uğradı veya geri alındı
ota.rollout.wave_completedBir dalga kapılarını geçti
ota.rollout.pausedBir kapı başarısız oldu veya bir kişi rollout’u duraklattı
ota.rollout.resumedBir kişi rollout’u sürdürdü
ota.rollout.completedSon dalga kapılarını geçti
ota.rollout.abortedBir kişi iptal etti, ataması kaldırıldı veya değiştirildi ya da paketi iptal edildi
{ "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 değeri download, verify, update veya rollback olur; error cihazın kodu ya da bir zaman aşımıdır.

{ "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 payload’ları rolloutId, assignmentId, packageId, status, wave (1’den başlar), waves ve at alanlarını taşır; ayrıca: updated, failures, successPct (dalga tamamlandı); reason ve sayılar (duraklatıldı; reason değeri failure_gate, success_gate, no_result (hiçbir cihaz bitirmedi) veya manual olur); pausedReason (sürdürüldü); updated (tamamlandı); reason (iptal edildi).

Provisioning

OlayGönderildiği an
iot.device.claimedLisanslı bir cihaz kuruluşunuza claim edildi
iot.device.releasedBir cihaz fabrika havuzuna geri döndü: kind değeri OWNER (siz bıraktınız), FORCED (platform desteği) veya DEVICE (cihazın kendi sayfasından)
{ "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" } }

Kurallar

OlayGönderildiği an
rules.mode_changedBir yer Manual moduna alındı, Auto’ya geri döndü veya Manual modu kendiliğinden sona erdi
rules.needs_attentionBir kural, adını verdiği cihaz veya yer artık olmadığı için kapatıldı
{ "event": "rules.mode_changed", "data": {
  "placeType": "asset", "placeId": "77aa…", "placeName": "Greenhouse 2", "mode": "manual", "change": "manual",
  "actorId": "u-55…", "until": 1762700000000, "reason": "Harvest" } }

change değeri manual, auto veya expired olur; bir Manual mod kendiliğinden bittiğinde actorId değeri null olur. Auto’ya geri dönüş ayrıca applyNow ve rearmed alanlarını taşır.

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

Flow’lar

automation.message yalnızca bir flow’un Webhook bloğu tarafından ve yalnızca bloğun adını verdiği tek endpoint’e gönderilir (bu endpoint “Automation message” olayına abone olmalıdır). topic, payload, originator, flowId, flowVersion, nodeId, actor ve bloğun listelediği metadata anahtarlarını X-Idempotency-Key ile birlikte taşır. Bkz. Action blocks.

Diğer olaylar

  • esim.operation.succeeded ve esim.operation.failed eSIM yönetimine aittir.
  • API anahtarı olayları (api_key.created, api_key.updated, api_key.rotated, api_key.deleted, api_key.expired) ve kuruluş olayları (üyeler, davetiyeler, abonelik) da sunulur. Bunların payload’ları bu sayfada ele alınmaz.