Webhooks

Les webhooks connectent dAio à vos propres systèmes. Plutôt que d'interroger la plateforme en continu, vous laissez dAio vous prévenir : dès qu'un événement se produit — une alerte météo déclenchée, un risque élevé détecté — dAio envoie en temps réel une requête HTTP signée vers l'endpoint de votre choix. Vous automatisez ainsi vos workflows : ouverture de tickets, notifications internes, mise à jour d'un tableau de bord métier ou déclenchement d'un plan d'action terrain.

C'est le pont entre les alertes de dAio et votre système d'information.

Astuce : commencez par un seul webhook abonné à un type d'événement, validez la chaîne de bout en bout, puis élargissez. Vous éviterez de noyer vos systèmes sous des notifications avant d'avoir fiabilisé le traitement.

Configurer un webhook

1. Accédez à Paramètres > Webhooks.
2. Cliquez sur Nouveau webhook.
3. Renseignez l'URL de destination : l'endpoint HTTPS de votre serveur (ex. https://votre-serveur.com/webhook).
4. Sélectionnez les événements à écouter en cliquant sur les étiquettes correspondantes.
5. Validez avec Créer.

Un secret est généré automatiquement à la création. Il sert à signer chaque requête en HMAC-SHA256 (voir plus bas) : conservez-le côté serveur, il vous permet de vérifier que chaque appel provient bien de dAio.

Attention : l'URL doit être en HTTPS et accessible publiquement. Un endpoint en HTTP simple ou derrière un pare-feu fermé ne pourra pas recevoir les livraisons.

Événements disponibles

Événement	Description
weather.alert	Une alerte météo a été déclenchée sur un site
weather.threshold	Un seuil météo personnalisé a été franchi
air_quality.alert	Une alerte qualité de l'air a été émise
pollen.alert	Une alerte pollen a été émise
marine.alert	Une alerte conditions marines a été émise
frost.alert	Une alerte gel a été déclenchée
storm.alert	Une alerte orage / tempête a été déclenchée
business.risk_high	Un niveau de risque élevé a été détecté pour votre activité

Astuce : abonnez chaque webhook uniquement aux événements réellement exploités par le système destinataire. Un endpoint « tickets » n'a pas besoin de recevoir les mêmes événements qu'un endpoint « tableau de bord ».

Format du payload

Chaque livraison est une requête POST dont le corps est un objet JSON. La structure générale est la suivante :

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

Le champ event identifie le type d'événement, timestamp indique la date d'émission (UTC, format ISO 8601) et data contient les détails propres à l'événement.

Authentification HMAC-SHA256

Chaque requête est signée avec votre secret via HMAC-SHA256. La signature est transmise dans le header X-Daio-Signature, au format sha256=<signature>.

Vérifiez systématiquement cette signature avant de traiter une requête : c'est ce qui garantit que l'appel provient de dAio et que le payload n'a pas été altéré.

Vérification côté serveur (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)

Attention : calculez la signature sur le corps brut de la requête (les octets reçus), avant toute désérialisation JSON. Le moindre reformatage modifie le hash et fait échouer la vérification.

Tester et déboguer

• Cliquez sur l'icône Tester (▶) en regard d'un webhook pour envoyer un événement factice à votre endpoint.
• Une réponse HTTP 2xx confirme que votre serveur a bien reçu et accepté la requête.
• Dépliez le webhook pour consulter ses dernières livraisons : code HTTP, type d'événement et horodatage.
• Un point de couleur indique l'état du webhook : vert = actif, rouge = désactivé après échecs répétés.

Historique des livraisons

Chaque envoi est journalisé. Dépliez un webhook pour voir, pour chaque tentative :

• Le code HTTP de réponse (vert si < 300, rouge sinon)
• Le type d'événement livré
• La date et l'heure de la tentative

Un compteur d'échecs s'affiche sur le webhook lorsque des livraisons ont échoué.

Tentatives et fiabilité

dAio retente automatiquement la livraison en cas d'échec, avec des intervalles croissants. Votre endpoint doit donc être idempotent : une même livraison peut arriver plusieurs fois, et votre traitement doit produire le même résultat sans effet de bord.

Attention : votre endpoint doit répondre en moins de 10 secondes avec un code HTTP 2xx. Au-delà, ou en cas de code d'erreur, la livraison est considérée comme échouée et sera réessayée. Après des échecs répétés, le webhook est automatiquement désactivé.

Bonnes pratiques

• Vérifiez toujours la signature HMAC avant de traiter un payload : ne faites jamais confiance à une requête non authentifiée.
• Répondez vite : renvoyez un 200 immédiatement, puis traitez la charge de travail en tâche de fond. Vous évitez les délais d'expiration et les retries inutiles.
• Rendez votre traitement idempotent pour absorber sans risque les livraisons multiples.
• Filtrez à la source : abonnez chaque webhook aux seuls événements utiles à son système destinataire.
• Surveillez le compteur d'échecs et l'historique des livraisons pour détecter rapidement un endpoint en panne avant qu'il ne soit désactivé.
• Utilisez le bouton Tester après chaque modification de votre côté (déploiement, changement d'URL) pour valider la chaîne sans attendre un événement réel.

Astuce : couplez vos webhooks aux alertes et au paramétrage de votre équipe pour acheminer automatiquement la bonne information vers le bon système. La disponibilité des webhooks dépend de votre abonnement.