Webhooks

Webhook'lar, dAio'yu kendi sistemlerinize bağlar. Platformu sürekli sorgulamak yerine, dAio'nun sizi haberdar etmesine izin verirsiniz: bir olay gerçekleşir gerçekleşmez — bir hava durumu uyarısı tetiklendiğinde, yüksek bir risk tespit edildiğinde — dAio, seçtiğiniz endpoint'e gerçek zamanlı olarak imzalı bir HTTP isteği gönderir. Böylece iş akışlarınızı otomatikleştirirsiniz: talep oluşturma, dahili bildirimler, bir iş panosunun güncellenmesi veya bir saha eylem planının tetiklenmesi.

Bu, dAio'nun uyarıları ile bilgi sisteminiz arasındaki köprüdür.

İpucu : tek bir olay türüne abone tek bir webhook ile başlayın, zinciri baştan sona doğrulayın, ardından genişletin. İşlemi güvenilir hale getirmeden önce sistemlerinizi bildirimlere boğmaktan kaçınırsınız.

Bir webhook yapılandırma

1. Ayarlar > Webhook'lar bölümüne gidin.
2. Yeni webhook'a tıklayın.
3. Hedef URL'yi girin: sunucunuzun HTTPS endpoint'i (örn. https://votre-serveur.com/webhook).
4. İlgili etiketlere tıklayarak dinlenecek olayları seçin.
5. Oluştur ile onaylayın.

Oluşturma sırasında otomatik olarak bir secret üretilir. Her isteği HMAC-SHA256 ile imzalamak için kullanılır (aşağıya bakın): bunu sunucu tarafında saklayın; her çağrının gerçekten dAio'dan geldiğini doğrulamanızı sağlar.

Dikkat : URL HTTPS olmalı ve herkese açık şekilde erişilebilir olmalıdır. Düz HTTP üzerindeki veya kapalı bir güvenlik duvarının arkasındaki bir endpoint, teslimatları alamayacaktır.

Kullanılabilir olaylar

Olay	Açıklama
weather.alert	Bir lokasyonda bir hava durumu uyarısı tetiklendi
weather.threshold	Özel bir hava durumu eşiği aşıldı
air_quality.alert	Bir hava kalitesi uyarısı yayınlandı
pollen.alert	Bir polen uyarısı yayınlandı
marine.alert	Bir deniz koşulları uyarısı yayınlandı
frost.alert	Bir don uyarısı tetiklendi
storm.alert	Bir fırtına uyarısı tetiklendi
business.risk_high	Faaliyetiniz için yüksek bir risk düzeyi tespit edildi

İpucu : her webhook'u yalnızca hedef sistem tarafından gerçekten kullanılan olaylara abone edin. Bir « talepler » endpoint'inin, bir « pano » endpoint'i ile aynı olayları almasına gerek yoktur.

Payload formatı

Her teslimat, gövdesi bir JSON nesnesi olan bir POST isteğidir. Genel yapı şöyledir:

{
  "event": "weather.alert",
  "timestamp": "2026-06-30T08:15:00Z",
  "data": {
    "site_id": 42,
    "site_name": "Entrepôt Nord",
    "severity": "high",
    "message": "Vent fort attendu (rafales > 80 km/h)"
  }
}

event alanı olay türünü tanımlar, timestamp gönderim zamanını belirtir (UTC, ISO 8601 formatı) ve data olaya özgü ayrıntıları içerir.

HMAC-SHA256 kimlik doğrulama

Her istek, secret'iniz ile HMAC-SHA256 üzerinden imzalanır. İmza, X-Daio-Signature başlığında sha256=<signature> formatında iletilir.

Bir isteği işlemeden önce bu imzayı her zaman doğrulayın: çağrının dAio'dan geldiğini ve payload'ın değiştirilmediğini garanti eden budur.

Sunucu tarafı doğrulama (Python):

import hmac, hashlib

def verify_webhook(payload, signature, secret):
    expected = hmac.new(
        secret.encode(), payload, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(f"sha256={expected}", signature)

Dikkat : imzayı, herhangi bir JSON ayrıştırmasından önce isteğin ham gövdesi (alınan baytlar) üzerinden hesaplayın. En küçük biçim değişikliği bile hash'i değiştirir ve doğrulamayı başarısız kılar.

Test etme ve hata ayıklama

• Endpoint'inize sahte bir olay göndermek için bir webhook'un yanındaki Test (▶) simgesine tıklayın.
• Bir 2xx HTTP yanıtı, sunucunuzun isteği aldığını ve kabul ettiğini onaylar.
• Webhook'u genişleterek son teslimatlarını görüntüleyin: HTTP kodu, olay türü ve zaman damgası.
• Renkli bir nokta webhook'un durumunu gösterir: yeşil = etkin, kırmızı = tekrarlanan başarısızlıklardan sonra devre dışı.

Teslimat geçmişi

Her gönderim günlüğe kaydedilir. Bir webhook'u genişleterek, her deneme için şunları görün:

• Yanıtın HTTP kodu (< 300 ise yeşil, aksi halde kırmızı)
• Teslim edilen olay türü
• Denemenin tarih ve saati

Teslimatlar başarısız olduğunda webhook üzerinde bir başarısızlık sayacı görüntülenir.

Yeniden denemeler ve güvenilirlik

dAio, başarısızlık durumunda artan aralıklarla teslimatı otomatik olarak yeniden dener. Bu nedenle endpoint'iniz idempotent olmalıdır: aynı teslimat birden çok kez gelebilir ve işleminiz yan etki olmadan aynı sonucu üretmelidir.

Dikkat : endpoint'iniz 10 saniyeden kısa sürede 2xx HTTP koduyla yanıt vermelidir. Bunun ötesinde veya bir hata kodu durumunda, teslimat başarısız sayılır ve yeniden denenir. Tekrarlanan başarısızlıklardan sonra webhook otomatik olarak devre dışı bırakılır.

En iyi uygulamalar

• Bir payload'ı işlemeden önce her zaman HMAC imzasını doğrulayın: kimliği doğrulanmamış bir isteğe asla güvenmeyin.
• Hızlı yanıt verin: hemen bir 200 döndürün, ardından iş yükünü arka planda işleyin. Zaman aşımlarından ve gereksiz yeniden denemelerden kaçınırsınız.
• Birden çok teslimatı güvenle absorbe etmek için işleminizi idempotent yapın.
• Kaynakta filtreleyin: her webhook'u yalnızca hedef sistemine yararlı olan olaylara abone edin.
• Devre dışı bırakılmadan önce arızalı bir endpoint'i hızla tespit etmek için başarısızlık sayacını ve teslimat geçmişini izleyin.
• Gerçek bir olayı beklemeden zinciri doğrulamak için kendi tarafınızdaki her değişiklikten sonra (dağıtım, URL değişikliği) Test düğmesini kullanın.

İpucu : doğru bilgiyi otomatik olarak doğru sisteme yönlendirmek için webhook'larınızı uyarılar ve ekibinizin yapılandırmasıyla birleştirin. Webhook'ların kullanılabilirliği aboneliğinize bağlıdır.