Webhooks

Webhooks verbinden dAio met uw eigen systemen. In plaats van het platform voortdurend te bevragen, laat u dAio u waarschuwen: zodra zich een gebeurtenis voordoet — een geactiveerde weerwaarschuwing, een gedetecteerd hoog risico — stuurt dAio in realtime een ondertekend HTTP-verzoek naar het eindpunt van uw keuze. Zo automatiseert u uw workflows: het openen van tickets, interne meldingen, het bijwerken van een bedrijfsdashboard of het in gang zetten van een actieplan op het terrein.

Het is de brug tussen de waarschuwingen van dAio en uw informatiesysteem.

Tip : begin met één enkele webhook die op één type gebeurtenis geabonneerd is, valideer de keten van begin tot eind en breid daarna uit. Zo voorkomt u dat u uw systemen overspoelt met meldingen voordat u de verwerking betrouwbaar hebt gemaakt.

Een webhook configureren

1. Ga naar Instellingen > Webhooks.
2. Klik op Nieuwe webhook.
3. Vul de bestemmings-URL in: het HTTPS-eindpunt van uw server (bijv. https://votre-serveur.com/webhook).
4. Selecteer de gebeurtenissen waarnaar u wilt luisteren door op de bijbehorende labels te klikken.
5. Bevestig met Aanmaken.

Bij het aanmaken wordt automatisch een geheim gegenereerd. Het dient om elk verzoek te ondertekenen met HMAC-SHA256 (zie hieronder): bewaar het aan de serverzijde, want daarmee kunt u controleren of elke aanroep werkelijk van dAio afkomstig is.

Let op : de URL moet HTTPS zijn en openbaar toegankelijk. Een eindpunt op gewone HTTP of achter een gesloten firewall kan geen leveringen ontvangen.

Beschikbare gebeurtenissen

Gebeurtenis	Beschrijving
weather.alert	Er is een weerwaarschuwing geactiveerd op een site
weather.threshold	Een aangepaste weerdrempel is overschreden
air_quality.alert	Er is een luchtkwaliteitswaarschuwing uitgegeven
pollen.alert	Er is een pollenwaarschuwing uitgegeven
marine.alert	Er is een waarschuwing voor mariene omstandigheden uitgegeven
frost.alert	Er is een vorstwaarschuwing geactiveerd
storm.alert	Er is een onweers- / stormwaarschuwing geactiveerd
business.risk_high	Er is een hoog risiconiveau gedetecteerd voor uw activiteit

Tip : abonneer elke webhook alleen op de gebeurtenissen die het ontvangende systeem daadwerkelijk gebruikt. Een "tickets"-eindpunt hoeft niet dezelfde gebeurtenissen te ontvangen als een "dashboard"-eindpunt.

Indeling van de payload

Elke levering is een POST-verzoek waarvan de body een JSON-object is. De algemene structuur is als volgt:

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

Het veld event identificeert het type gebeurtenis, timestamp geeft het tijdstip van uitgifte aan (UTC, ISO 8601-formaat) en data bevat de specifieke details van de gebeurtenis.

HMAC-SHA256-authenticatie

Elk verzoek wordt met uw geheim ondertekend via HMAC-SHA256. De handtekening wordt verzonden in de header X-Daio-Signature, in de indeling sha256=<signature>.

Controleer deze handtekening systematisch voordat u een verzoek verwerkt: dat is wat garandeert dat de aanroep van dAio afkomstig is en dat de payload niet is gewijzigd.

Verificatie aan de serverzijde (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)

Let op : bereken de handtekening over de ruwe body van het verzoek (de ontvangen bytes), vóór elke JSON-deserialisatie. De geringste herformattering verandert de hash en laat de verificatie mislukken.

Testen en debuggen

• Klik op het pictogram Testen (▶) naast een webhook om een fictieve gebeurtenis naar uw eindpunt te sturen.
• Een HTTP-2xx-antwoord bevestigt dat uw server het verzoek heeft ontvangen en geaccepteerd.
• Klap de webhook uit om de laatste leveringen te bekijken: HTTP-code, type gebeurtenis en tijdstempel.
• Een gekleurde stip geeft de status van de webhook aan: groen = actief, rood = uitgeschakeld na herhaalde mislukkingen.

Leveringsgeschiedenis

Elke verzending wordt gelogd. Klap een webhook uit om voor elke poging te zien:

• De HTTP-code van de respons (groen indien < 300, anders rood)
• Het geleverde type gebeurtenis
• De datum en tijd van de poging

Er verschijnt een teller met mislukkingen op de webhook wanneer er leveringen zijn mislukt.

Nieuwe pogingen en betrouwbaarheid

dAio probeert de levering bij een mislukking automatisch opnieuw, met toenemende intervallen. Uw eindpunt moet daarom idempotent zijn: dezelfde levering kan meerdere keren binnenkomen, en uw verwerking moet hetzelfde resultaat opleveren zonder neveneffecten.

Let op : uw eindpunt moet binnen 10 seconden antwoorden met een HTTP-2xx-code. Daarboven, of bij een foutcode, wordt de levering als mislukt beschouwd en opnieuw geprobeerd. Na herhaalde mislukkingen wordt de webhook automatisch uitgeschakeld.

Best practices

• Controleer altijd de HMAC-handtekening voordat u een payload verwerkt: vertrouw nooit op een niet-geauthenticeerd verzoek.
• Reageer snel: stuur onmiddellijk een 200 terug en verwerk de werklast daarna op de achtergrond. Zo voorkomt u time-outs en onnodige nieuwe pogingen.
• Maak uw verwerking idempotent om meervoudige leveringen zonder risico op te vangen.
• Filter bij de bron: abonneer elke webhook alleen op de gebeurtenissen die nuttig zijn voor zijn ontvangende systeem.
• Houd de mislukkingenteller en de leveringsgeschiedenis in de gaten om een defect eindpunt snel te detecteren voordat het wordt uitgeschakeld.
• Gebruik de knop Testen na elke wijziging aan uw kant (uitrol, URL-wijziging) om de keten te valideren zonder op een echte gebeurtenis te wachten.

Tip : combineer uw webhooks met de waarschuwingen en de instellingen van uw team om automatisch de juiste informatie naar het juiste systeem te leiden. De beschikbaarheid van webhooks hangt af van uw abonnement.