Γεγονότα webhooks

Κατάλογος γεγονότων

Γεγονός	Πότε στέλνεται	Χρήση
trip.ended	Μια διαδρομή κλείνει (μόνο διαδρομές που τελειώνουν μέσα στο διάστημα συγχρονισμού, έτσι ο πρώτος συγχρονισμός δεν ξαναστέλνει το ιστορικό).	Καταχώριση χιλιομέτρων.
geofence.enter	Ένα συνδεδεμένο όχημα μπαίνει σε μία από τις ζώνες σας.	Ώρες παράδοσης.
geofence.exit	Ένα συνδεδεμένο όχημα βγαίνει από μία από τις ζώνες σας.	Διάρκεια επισκέψεων.
alarm.critical	Ενεργοποιείται SOS, σύγκρουση ή ανατροπή.	Άνοιγμα συμβάντος.
report.daily	Τελειώνει η νυχτερινή αποστολή αναφορών με email για τον οργανισμό.	Επιβεβαίωση ότι η ημέρα έκλεισε.
webhook.test	Μόνο από το κουμπί δοκιμής — ποτέ από πραγματική δραστηριότητα.	Έλεγχος της αλυσίδας.

Κάθε παράδοση είναι ένα POST με JSON και δύο κεφαλίδες: X-Filodos-Signature (HMAC-SHA256 σε δεκαεξαδική μορφή, πάνω στο ακατέργαστο σώμα, με κλειδί το μυστικό της συνδρομής) και X-Filodos-Delivery (μοναδικός αριθμός για κάθε παράδοση — αποθηκεύστε τον και αγνοήστε τις επαναλήψεις).

Έως τον Σεπτέμβριο του 2027, κάθε παράδοση περιέχει τις ίδιες τιμές και στις παλιές κεφαλίδες X-Avlo-Signature και X-Avlo-Delivery. Αλλάξτε το σύστημά σας στις κεφαλίδες X-Filodos- πριν από αυτή την ημερομηνία.

Φάκελοι

Οι ειδοποιήσεις συμβάντων (geofence.enter, geofence.exit, alarm.critical) έχουν κοινή μορφή. Το attributes περιέχει λεπτομέρειες του τύπου, όπως το geofenceId:

{"event": "geofence.enter", "delivery_id": "947c…",
 "organization": "acme", "device_id": 43,
 "unique_id": "359876543210987",
 "occurred_at": "2026-10-05T08:00:00+00:00",
 "event_type": "geofenceEnter", "traccar_event_id": 101,
 "attributes": {"geofenceId": 5}}

Το trip.ended περιέχει τη διαδρομή που έκλεισε:

{"event": "trip.ended", "delivery_id": "a41d…",
 "organization": "acme", "device_id": 43,
 "unique_id": "359876543210987",
 "occurred_at": "2026-10-05T06:47:03+00:00",
 "trip": {"id": 812, "started_at": "2026-10-05T06:02:11+00:00",
          "ended_at": "2026-10-05T06:47:03+00:00", "distance_km": 24.6}}

Το report.daily περιέχει το αποτέλεσμα της αποστολής:

{"event": "report.daily", "delivery_id": "77e0…",
 "organization": "acme", "period_start": "2026-10-04",
 "sent": 3, "failed": 0}

Έλεγχος υπογραφής

Απορρίψτε κάθε παράδοση με υπογραφή που δεν ταιριάζει — μόνο μετά διαβάστε το σώμα. Παράδειγμα σε Python:

import hashlib, hmac

def trusted(raw_body: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature)

Συγκρίνετε σε σταθερό χρόνο (hmac.compare_digest, ποτέ ==), πάνω στα ακατέργαστα bytes του σώματος, πριν από την ανάλυση του JSON. Οι παραδόσεις γίνονται χωρίς εγγύηση, με σύντομο χρονικό όριο και ακόμη χωρίς αυτόματες επαναλήψεις — κρατήστε το API ανάγνωσης ως την πηγή αλήθειας και τα webhooks ως το έναυσμα.