Webhooks

Webhooky propojují dAio s vašimi vlastními systémy. Místo neustálého dotazování platformy necháte dAio, aby vás upozornil: jakmile nastane událost — spuštěné meteorologické upozornění, zjištěné vysoké riziko — dAio v reálném čase odešle podepsaný HTTP požadavek na vámi zvolený endpoint. Tímto způsobem automatizujete své pracovní postupy: otevírání tiketů, interní oznámení, aktualizaci provozního dashboardu nebo spuštění akčního plánu v terénu.

Je to most mezi upozorněními dAio a vaším informačním systémem.

Tip : začněte s jediným webhookem přihlášeným k jednomu typu události, ověřte řetězec od začátku do konce a poté rozšiřujte. Vyhnete se zahlcení svých systémů oznámeními dříve, než spolehlivě zajistíte zpracování.

Konfigurace webhooku

1. Přejděte do Nastavení > Webhooky.
2. Klikněte na Nový webhook.
3. Vyplňte cílovou URL: HTTPS endpoint vašeho serveru (např. https://votre-serveur.com/webhook).
4. Vyberte události k naslouchání kliknutím na odpovídající štítky.
5. Potvrďte tlačítkem Vytvořit.

Při vytvoření se automaticky vygeneruje secret. Slouží k podpisu každého požadavku pomocí HMAC-SHA256 (viz níže): uchovávejte jej na straně serveru, umožňuje vám ověřit, že každé volání skutečně pochází z dAio.

Upozornění : URL musí být v HTTPS a veřejně dostupná. Endpoint v prostém HTTP nebo za uzavřeným firewallem nebude moci přijímat doručení.

Dostupné události

Událost	Popis
weather.alert	Pro lokalitu bylo spuštěno meteorologické upozornění
weather.threshold	Byl překročen vlastní meteorologický práh
air_quality.alert	Bylo vydáno upozornění na kvalitu ovzduší
pollen.alert	Bylo vydáno upozornění na pyl
marine.alert	Bylo vydáno upozornění na mořské podmínky
frost.alert	Bylo spuštěno upozornění na mráz
storm.alert	Bylo spuštěno upozornění na bouři / vichřici
business.risk_high	Pro vaši činnost byla zjištěna vysoká úroveň rizika

Tip : přihlaste každý webhook pouze k událostem, které cílový systém skutečně využívá. Endpoint „tikety“ nepotřebuje přijímat stejné události jako endpoint „dashboard“.

Formát payloadu

Každé doručení je požadavek POST, jehož tělo je objekt JSON. Obecná struktura je následující:

{
  "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 identifikuje typ události, timestamp udává datum vydání (UTC, formát ISO 8601) a data obsahuje podrobnosti specifické pro danou událost.

Ověřování HMAC-SHA256

Každý požadavek je podepsán vaším secretem pomocí HMAC-SHA256. Podpis je předáván v hlavičce X-Daio-Signature, ve formátu sha256=<signature>.

Tento podpis systematicky ověřujte před zpracováním požadavku: právě to zaručuje, že volání pochází z dAio a že payload nebyl pozměněn.

Ověření na straně serveru (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)

Upozornění : počítejte podpis ze surového těla požadavku (přijaté bajty), před jakoukoli deserializací JSON. Sebemenší přeformátování změní hash a způsobí selhání ověření.

Testování a ladění

• Klikněte na ikonu Testovat (▶) vedle webhooku, abyste odeslali fiktivní událost na svůj endpoint.
• Odpověď HTTP 2xx potvrzuje, že váš server požadavek správně přijal a akceptoval.
• Rozbalte webhook, abyste si prohlédli jeho poslední doručení: HTTP kód, typ události a časové razítko.
• Barevný puntík indikuje stav webhooku: zelená = aktivní, červená = deaktivován po opakovaných selháních.

Historie doručení

Každé odeslání je zaznamenáno. Rozbalte webhook, abyste pro každý pokus viděli:

• HTTP kód odpovědi (zelená, pokud < 300, jinak červená)
• Typ doručené události
• Datum a čas pokusu

Počítadlo selhání se na webhooku zobrazí, když některá doručení selhala.

Pokusy a spolehlivost

dAio v případě selhání doručení automaticky opakuje, s rostoucími intervaly. Váš endpoint proto musí být idempotentní: stejné doručení může dorazit vícekrát a vaše zpracování musí produkovat stejný výsledek bez vedlejších účinků.

Upozornění : váš endpoint musí odpovědět do méně než 10 sekund s HTTP kódem 2xx. Po překročení tohoto limitu nebo v případě chybového kódu je doručení považováno za neúspěšné a bude zopakováno. Po opakovaných selháních je webhook automaticky deaktivován.

Osvědčené postupy

• Vždy ověřte podpis HMAC před zpracováním payloadu: nikdy nedůvěřujte neověřenému požadavku.
• Odpovídejte rychle: ihned vraťte 200 a poté zpracujte zátěž na pozadí. Vyhnete se vypršení časových limitů a zbytečným opakováním.
• Učiňte své zpracování idempotentním, abyste bez rizika absorbovali vícenásobná doručení.
• Filtrujte u zdroje: přihlaste každý webhook pouze k událostem užitečným pro jeho cílový systém.
• Sledujte počítadlo selhání a historii doručení, abyste rychle odhalili nefunkční endpoint dříve, než bude deaktivován.
• Používejte tlačítko Testovat po každé úpravě na vaší straně (nasazení, změna URL), abyste ověřili řetězec bez čekání na skutečnou událost.

Tip : propojte své webhooky s upozorněními a s nastavením vašeho týmu, abyste automaticky směrovali správnou informaci do správného systému. Dostupnost webhooků závisí na vašem předplatném.