Webhooks

Τα webhooks συνδέουν το dAio με τα δικά σας συστήματα. Αντί να ερωτάτε συνεχώς την πλατφόρμα, αφήνετε το dAio να σας ειδοποιεί: μόλις συμβεί ένα συμβάν — μια ενεργοποιημένη ειδοποίηση καιρού, ένας εντοπισμένος υψηλός κίνδυνος — το dAio αποστέλλει σε πραγματικό χρόνο ένα υπογεγραμμένο HTTP αίτημα προς το endpoint της επιλογής σας. Έτσι αυτοματοποιείτε τις ροές εργασίας σας: άνοιγμα δελτίων, εσωτερικές ειδοποιήσεις, ενημέρωση ενός επιχειρησιακού πίνακα ελέγχου ή ενεργοποίηση ενός σχεδίου δράσης πεδίου.

Είναι η γέφυρα μεταξύ των ειδοποιήσεων του dAio και του πληροφοριακού σας συστήματος.

Συμβουλή : ξεκινήστε με ένα μόνο webhook εγγεγραμμένο σε έναν τύπο συμβάντος, επικυρώστε την αλυσίδα από άκρη σε άκρη, και έπειτα επεκταθείτε. Θα αποφύγετε να πνίξετε τα συστήματά σας σε ειδοποιήσεις προτού να έχετε αξιοπιστοποιήσει την επεξεργασία.

Διαμόρφωση ενός webhook

1. Μεταβείτε στις Ρυθμίσεις > Webhooks.
2. Κάντε κλικ στο Νέο webhook.
3. Συμπληρώστε το URL προορισμού: το HTTPS endpoint του διακομιστή σας (π.χ. https://votre-serveur.com/webhook).
4. Επιλέξτε τα συμβάντα προς ακρόαση κάνοντας κλικ στις αντίστοιχες ετικέτες.
5. Επικυρώστε με Δημιουργία.

Ένα secret δημιουργείται αυτόματα κατά τη δημιουργία. Χρησιμεύει για την υπογραφή κάθε αιτήματος σε HMAC-SHA256 (δείτε παρακάτω): διατηρήστε το στην πλευρά του διακομιστή, σας επιτρέπει να επαληθεύετε ότι κάθε κλήση προέρχεται όντως από το dAio.

Προσοχή : το URL πρέπει να είναι σε HTTPS και δημόσια προσβάσιμο. Ένα endpoint σε απλό HTTP ή πίσω από κλειστό τείχος προστασίας δεν θα μπορέσει να λάβει τις παραδόσεις.

Διαθέσιμα συμβάντα

Συμβάν	Περιγραφή
weather.alert	Ενεργοποιήθηκε μια ειδοποίηση καιρού σε μια τοποθεσία
weather.threshold	Ξεπεράστηκε ένα προσαρμοσμένο όριο καιρού
air_quality.alert	Εκδόθηκε μια ειδοποίηση ποιότητας αέρα
pollen.alert	Εκδόθηκε μια ειδοποίηση γύρης
marine.alert	Εκδόθηκε μια ειδοποίηση θαλάσσιων συνθηκών
frost.alert	Ενεργοποιήθηκε μια ειδοποίηση παγετού
storm.alert	Ενεργοποιήθηκε μια ειδοποίηση καταιγίδας / θύελλας
business.risk_high	Εντοπίστηκε υψηλό επίπεδο κινδύνου για τη δραστηριότητά σας

Συμβουλή : εγγράψτε κάθε webhook μόνο στα συμβάντα που πραγματικά αξιοποιούνται από το σύστημα παραλήπτη. Ένα endpoint «δελτίων» δεν χρειάζεται να λαμβάνει τα ίδια συμβάντα με ένα endpoint «πίνακα ελέγχου».

Μορφή του payload

Κάθε παράδοση είναι ένα αίτημα POST του οποίου το σώμα είναι ένα αντικείμενο JSON. Η γενική δομή είναι η εξής:

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

Το πεδίο event προσδιορίζει τον τύπο του συμβάντος, το timestamp υποδεικνύει την ημερομηνία έκδοσης (UTC, μορφή ISO 8601) και το data περιέχει τις λεπτομέρειες που αφορούν το συμβάν.

Έλεγχος ταυτότητας HMAC-SHA256

Κάθε αίτημα υπογράφεται με το secret σας μέσω HMAC-SHA256. Η υπογραφή μεταδίδεται στο header X-Daio-Signature, σε μορφή sha256=<signature>.

Επαληθεύετε συστηματικά αυτή την υπογραφή προτού επεξεργαστείτε ένα αίτημα: αυτό εγγυάται ότι η κλήση προέρχεται από το dAio και ότι το payload δεν έχει αλλοιωθεί.

Επαλήθευση στην πλευρά του διακομιστή (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)

Προσοχή : υπολογίστε την υπογραφή στο ακατέργαστο σώμα του αιτήματος (τα bytes που ελήφθησαν), πριν από οποιαδήποτε αποσειριοποίηση JSON. Η παραμικρή αναμορφοποίηση τροποποιεί το hash και προκαλεί αποτυχία της επαλήθευσης.

Δοκιμή και αποσφαλμάτωση

• Κάντε κλικ στο εικονίδιο Δοκιμή (▶) δίπλα σε ένα webhook για να στείλετε ένα εικονικό συμβάν στο endpoint σας.
• Μια απόκριση HTTP 2xx επιβεβαιώνει ότι ο διακομιστής σας έλαβε και αποδέχθηκε σωστά το αίτημα.
• Αναπτύξτε το webhook για να συμβουλευτείτε τις τελευταίες παραδόσεις του: κωδικός HTTP, τύπος συμβάντος και χρονοσήμανση.
• Μια έγχρωμη κουκκίδα υποδεικνύει την κατάσταση του webhook: πράσινο = ενεργό, κόκκινο = απενεργοποιημένο μετά από επανειλημμένες αποτυχίες.

Ιστορικό παραδόσεων

Κάθε αποστολή καταγράφεται. Αναπτύξτε ένα webhook για να δείτε, για κάθε προσπάθεια:

• Τον κωδικό HTTP απόκρισης (πράσινο αν < 300, κόκκινο διαφορετικά)
• Τον τύπο συμβάντος που παραδόθηκε
• Την ημερομηνία και ώρα της προσπάθειας

Ένας μετρητής αποτυχιών εμφανίζεται στο webhook όταν κάποιες παραδόσεις έχουν αποτύχει.

Προσπάθειες και αξιοπιστία

Το dAio επαναλαμβάνει αυτόματα την παράδοση σε περίπτωση αποτυχίας, με αυξανόμενα διαστήματα. Επομένως, το endpoint σας πρέπει να είναι idempotent: η ίδια παράδοση μπορεί να φτάσει πολλές φορές, και η επεξεργασία σας πρέπει να παράγει το ίδιο αποτέλεσμα χωρίς παρενέργειες.

Προσοχή : το endpoint σας πρέπει να αποκρίνεται σε λιγότερο από 10 δευτερόλεπτα με κωδικό HTTP 2xx. Πέραν αυτού, ή σε περίπτωση κωδικού σφάλματος, η παράδοση θεωρείται αποτυχημένη και θα επαναληφθεί. Μετά από επανειλημμένες αποτυχίες, το webhook απενεργοποιείται αυτόματα.

Βέλτιστες πρακτικές

• Επαληθεύετε πάντα την υπογραφή HMAC προτού επεξεργαστείτε ένα payload: μην εμπιστεύεστε ποτέ ένα μη πιστοποιημένο αίτημα.
• Απαντάτε γρήγορα: επιστρέψτε αμέσως ένα 200, και έπειτα επεξεργαστείτε τον φόρτο εργασίας στο παρασκήνιο. Αποφεύγετε τις λήξεις χρόνου και τις περιττές επαναλήψεις.
• Καταστήστε την επεξεργασία σας idempotent για να απορροφάτε χωρίς κίνδυνο τις πολλαπλές παραδόσεις.
• Φιλτράρετε στην πηγή: εγγράψτε κάθε webhook μόνο στα συμβάντα που είναι χρήσιμα στο σύστημα παραλήπτη του.
• Παρακολουθείτε τον μετρητή αποτυχιών και το ιστορικό παραδόσεων για να εντοπίζετε γρήγορα ένα endpoint εκτός λειτουργίας προτού απενεργοποιηθεί.
• Χρησιμοποιείτε το κουμπί Δοκιμή μετά από κάθε τροποποίηση από την πλευρά σας (deployment, αλλαγή URL) για να επικυρώνετε την αλυσίδα χωρίς να περιμένετε ένα πραγματικό συμβάν.

Συμβουλή : συνδυάστε τα webhooks σας με τις ειδοποιήσεις και τη διαμόρφωση της ομάδας σας για να δρομολογείτε αυτόματα τη σωστή πληροφορία προς το σωστό σύστημα. Η διαθεσιμότητα των webhooks εξαρτάται από τη συνδρομή σας.