Webhooks

Webhooks verbinden dAio mit Ihren eigenen Systemen. Anstatt die Plattform fortlaufend abzufragen, lassen Sie sich von dAio benachrichtigen: Sobald ein Ereignis eintritt — eine ausgelöste Wetterwarnung, ein erkanntes hohes Risiko — sendet dAio in Echtzeit eine signierte HTTP-Anfrage an den Endpunkt Ihrer Wahl. So automatisieren Sie Ihre Workflows: Eröffnen von Tickets, interne Benachrichtigungen, Aktualisierung eines Business-Dashboards oder Auslösen eines Einsatzplans vor Ort.

Sie ist die Brücke zwischen den Warnungen von dAio und Ihrem Informationssystem.

Tipp : Beginnen Sie mit einem einzigen Webhook, der einen Ereignistyp abonniert, validieren Sie die Kette von Anfang bis Ende und erweitern Sie sie dann. So vermeiden Sie es, Ihre Systeme mit Benachrichtigungen zu überfluten, bevor die Verarbeitung zuverlässig läuft.

Einen Webhook konfigurieren

1. Gehen Sie zu Einstellungen > Webhooks.
2. Klicken Sie auf Neuer Webhook.
3. Geben Sie die Ziel-URL ein: den HTTPS-Endpunkt Ihres Servers (z. B. https://votre-serveur.com/webhook).
4. Wählen Sie die zu überwachenden Ereignisse aus, indem Sie auf die entsprechenden Etiketten klicken.
5. Bestätigen Sie mit Erstellen.

Bei der Erstellung wird automatisch ein Secret generiert. Es dient dazu, jede Anfrage mit HMAC-SHA256 zu signieren (siehe unten): Bewahren Sie es serverseitig auf, denn damit können Sie überprüfen, dass jeder Aufruf tatsächlich von dAio stammt.

Achtung : Die URL muss HTTPS und öffentlich erreichbar sein. Ein Endpunkt mit einfachem HTTP oder hinter einer geschlossenen Firewall kann keine Zustellungen empfangen.

Verfügbare Ereignisse

Ereignis	Beschreibung
weather.alert	An einem Standort wurde eine Wetterwarnung ausgelöst
weather.threshold	Ein benutzerdefinierter Wetterschwellenwert wurde überschritten
air_quality.alert	Eine Luftqualitätswarnung wurde ausgegeben
pollen.alert	Eine Pollenwarnung wurde ausgegeben
marine.alert	Eine Warnung zu maritimen Bedingungen wurde ausgegeben
frost.alert	Eine Frostwarnung wurde ausgelöst
storm.alert	Eine Sturm-/Unwetterwarnung wurde ausgelöst
business.risk_high	Für Ihre Tätigkeit wurde ein hohes Risikoniveau erkannt

Tipp : Abonnieren Sie jeden Webhook nur für die Ereignisse, die das Zielsystem tatsächlich nutzt. Ein „Tickets"-Endpunkt muss nicht dieselben Ereignisse empfangen wie ein „Dashboard"-Endpunkt.

Format des Payloads

Jede Zustellung ist eine POST-Anfrage, deren Body ein JSON-Objekt ist. Die allgemeine Struktur lautet wie folgt:

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

Das Feld event identifiziert den Ereignistyp, timestamp gibt den Zeitpunkt der Ausgabe an (UTC, ISO-8601-Format) und data enthält die ereignisspezifischen Details.

HMAC-SHA256-Authentifizierung

Jede Anfrage wird mit Ihrem Secret per HMAC-SHA256 signiert. Die Signatur wird im Header X-Daio-Signature im Format sha256=<signature> übermittelt.

Überprüfen Sie diese Signatur grundsätzlich, bevor Sie eine Anfrage verarbeiten: Sie ist es, die garantiert, dass der Aufruf von dAio stammt und dass der Payload nicht verändert wurde.

Serverseitige Überprüfung (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)

Achtung : Berechnen Sie die Signatur über den rohen Body der Anfrage (die empfangenen Bytes), vor jeder JSON-Deserialisierung. Schon die geringste Umformatierung verändert den Hash und lässt die Überprüfung fehlschlagen.

Testen und Debuggen

• Klicken Sie auf das Symbol Testen (▶) neben einem Webhook, um ein Dummy-Ereignis an Ihren Endpunkt zu senden.
• Eine HTTP-Antwort 2xx bestätigt, dass Ihr Server die Anfrage empfangen und akzeptiert hat.
• Klappen Sie den Webhook auf, um seine letzten Zustellungen einzusehen: HTTP-Code, Ereignistyp und Zeitstempel.
• Ein farbiger Punkt zeigt den Status des Webhooks an: grün = aktiv, rot = nach wiederholten Fehlern deaktiviert.

Zustellungsverlauf

Jeder Versand wird protokolliert. Klappen Sie einen Webhook auf, um für jeden Versuch zu sehen:

• Den HTTP-Code der Antwort (grün bei < 300, sonst rot)
• Den zugestellten Ereignistyp
• Datum und Uhrzeit des Versuchs

Ein Fehlerzähler erscheint auf dem Webhook, wenn Zustellungen fehlgeschlagen sind.

Wiederholungen und Zuverlässigkeit

dAio wiederholt die Zustellung bei einem Fehlschlag automatisch, mit zunehmenden Intervallen. Ihr Endpunkt muss daher idempotent sein: Dieselbe Zustellung kann mehrmals eintreffen, und Ihre Verarbeitung muss dasselbe Ergebnis ohne Nebenwirkungen erzeugen.

Achtung : Ihr Endpunkt muss innerhalb von 10 Sekunden mit einem HTTP-Code 2xx antworten. Darüber hinaus oder im Fall eines Fehlercodes gilt die Zustellung als fehlgeschlagen und wird erneut versucht. Nach wiederholten Fehlern wird der Webhook automatisch deaktiviert.

Bewährte Praktiken

• Überprüfen Sie immer die HMAC-Signatur, bevor Sie einen Payload verarbeiten: Vertrauen Sie niemals einer nicht authentifizierten Anfrage.
• Antworten Sie schnell: Geben Sie sofort eine 200 zurück und verarbeiten Sie die Arbeitslast anschließend im Hintergrund. So vermeiden Sie Zeitüberschreitungen und unnötige Wiederholungen.
• Machen Sie Ihre Verarbeitung idempotent, um mehrfache Zustellungen risikolos abzufangen.
• Filtern Sie an der Quelle: Abonnieren Sie jeden Webhook nur für die Ereignisse, die für sein Zielsystem nützlich sind.
• Überwachen Sie den Fehlerzähler und den Zustellungsverlauf, um einen ausgefallenen Endpunkt schnell zu erkennen, bevor er deaktiviert wird.
• Nutzen Sie die Schaltfläche Testen nach jeder Änderung auf Ihrer Seite (Deployment, URL-Änderung), um die Kette zu validieren, ohne auf ein echtes Ereignis zu warten.

Tipp : Kombinieren Sie Ihre Webhooks mit den Warnungen und der Konfiguration Ihres Teams, um automatisch die richtige Information an das richtige System zu leiten. Die Verfügbarkeit der Webhooks hängt von Ihrem Abonnement ab.