Webhooks

Webhooki łączą dAio z Twoimi własnymi systemami. Zamiast nieustannie odpytywać platformę, pozwalasz, by to dAio Cię powiadamiał: gdy tylko zachodzi zdarzenie — wyzwolony alert pogodowy, wykryte wysokie ryzyko — dAio wysyła w czasie rzeczywistym podpisane żądanie HTTP do wybranego przez Ciebie endpointu. W ten sposób automatyzujesz swoje przepływy pracy: otwieranie zgłoszeń, powiadomienia wewnętrzne, aktualizację pulpitu biznesowego lub uruchomienie planu działania w terenie.

To pomost między alertami dAio a Twoim systemem informatycznym.

Wskazówka : zacznij od jednego webhooka subskrybującego jeden typ zdarzenia, zwaliduj cały łańcuch od początku do końca, a następnie rozszerzaj. Unikniesz zalania swoich systemów powiadomieniami, zanim usprawnisz ich przetwarzanie.

Konfigurowanie webhooka

1. Przejdź do Ustawienia > Webhooki.
2. Kliknij Nowy webhook.
3. Wpisz adres URL docelowy: endpoint HTTPS Twojego serwera (np. https://votre-serveur.com/webhook).
4. Wybierz zdarzenia do nasłuchiwania, klikając odpowiednie etykiety.
5. Zatwierdź przyciskiem Utwórz.

Przy tworzeniu automatycznie generowany jest sekret. Służy on do podpisywania każdego żądania za pomocą HMAC-SHA256 (zob. dalej): przechowuj go po stronie serwera, ponieważ pozwala zweryfikować, że każde wywołanie pochodzi rzeczywiście od dAio.

Uwaga : adres URL musi być w HTTPS i publicznie dostępny. Endpoint w zwykłym HTTP lub za zamkniętą zaporą sieciową nie będzie mógł odbierać dostaw.

Dostępne zdarzenia

Zdarzenie	Opis
weather.alert	Wyzwolono alert pogodowy na obiekcie
weather.threshold	Przekroczono niestandardowy próg pogodowy
air_quality.alert	Wydano alert jakości powietrza
pollen.alert	Wydano alert pyłkowy
marine.alert	Wydano alert warunków morskich
frost.alert	Wyzwolono alert przymrozkowy
storm.alert	Wyzwolono alert burzy / nawałnicy
business.risk_high	Wykryto wysoki poziom ryzyka dla Twojej działalności

Wskazówka : subskrybuj każdy webhook wyłącznie do zdarzeń rzeczywiście wykorzystywanych przez system docelowy. Endpoint «zgłoszenia» nie musi otrzymywać tych samych zdarzeń co endpoint «pulpit».

Format ładunku (payload)

Każda dostawa to żądanie POST, którego treścią jest obiekt JSON. Ogólna struktura jest następująca:

{
  "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)"
  }
}

Pole event identyfikuje typ zdarzenia, timestamp wskazuje datę wystawienia (UTC, format ISO 8601), a data zawiera szczegóły właściwe dla zdarzenia.

Uwierzytelnianie HMAC-SHA256

Każde żądanie jest podpisywane Twoim sekretem za pomocą HMAC-SHA256. Podpis przekazywany jest w nagłówku X-Daio-Signature, w formacie sha256=<signature>.

Weryfikuj ten podpis systematycznie przed przetworzeniem żądania: to właśnie gwarantuje, że wywołanie pochodzi od dAio i że ładunek nie został zmieniony.

Weryfikacja po stronie serwera (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)

Uwaga : oblicz podpis na surowej treści żądania (otrzymanych bajtach), przed jakąkolwiek deserializacją JSON. Najmniejsze przeformatowanie zmienia hash i powoduje niepowodzenie weryfikacji.

Testowanie i debugowanie

• Kliknij ikonę Testuj (▶) obok webhooka, aby wysłać fikcyjne zdarzenie do swojego endpointu.
• Odpowiedź HTTP 2xx potwierdza, że Twój serwer odebrał i zaakceptował żądanie.
• Rozwiń webhook, aby zobaczyć jego ostatnie dostawy: kod HTTP, typ zdarzenia i znacznik czasu.
• Kolorowa kropka wskazuje stan webhooka: zielona = aktywny, czerwona = wyłączony po powtarzających się niepowodzeniach.

Historia dostaw

Każda wysyłka jest rejestrowana. Rozwiń webhook, aby zobaczyć dla każdej próby:

• Kod HTTP odpowiedzi (zielony, jeśli < 300, w przeciwnym razie czerwony)
• Dostarczony typ zdarzenia
• Datę i godzinę próby

Licznik niepowodzeń wyświetla się na webhooku, gdy dostawy się nie powiodły.

Ponowne próby i niezawodność

dAio automatycznie ponawia dostawę w razie niepowodzenia, z rosnącymi odstępami. Twój endpoint musi więc być idempotentny: ta sama dostawa może dotrzeć wielokrotnie, a Twoje przetwarzanie musi dawać ten sam wynik bez efektów ubocznych.

Uwaga : Twój endpoint musi odpowiedzieć w czasie krótszym niż 10 sekund kodem HTTP 2xx. Powyżej tego czasu lub w przypadku kodu błędu dostawa jest uznawana za nieudaną i zostanie ponowiona. Po powtarzających się niepowodzeniach webhook jest automatycznie wyłączany.

Dobre praktyki

• Zawsze weryfikuj podpis HMAC przed przetworzeniem ładunku: nigdy nie ufaj nieuwierzytelnionemu żądaniu.
• Odpowiadaj szybko: zwróć natychmiast 200, a następnie przetwarzaj obciążenie w tle. Unikniesz przekroczeń limitu czasu i zbędnych ponowień.
• Uczyń swoje przetwarzanie idempotentnym, aby bezpiecznie przyjmować wielokrotne dostawy.
• Filtruj u źródła: subskrybuj każdy webhook wyłącznie do zdarzeń przydatnych dla jego systemu docelowego.
• Monitoruj licznik niepowodzeń i historię dostaw, aby szybko wykryć uszkodzony endpoint, zanim zostanie wyłączony.
• Używaj przycisku Testuj po każdej zmianie po Twojej stronie (wdrożenie, zmiana adresu URL), aby zwalidować łańcuch bez czekania na rzeczywiste zdarzenie.

Wskazówka : połącz swoje webhooki z alertami oraz z konfiguracją swojego zespołu, aby automatycznie kierować właściwą informację do właściwego systemu. Dostępność webhooków zależy od Twojej subskrypcji.