Webhook signatures: πώς επαληθεύετε ότι ένα event είναι αυθεντικό

Ένα webhook endpoint είναι δημόσια διεύθυνση που δέχεται εντολές από το internet. Αν η εφαρμογή εμπιστεύεται οποιοδήποτε POST φτάσει εκεί, ένας τρίτος μπορεί να προσποιηθεί ότι η πληρωμή ολοκληρώθηκε, ότι μια παραγγελία στάλθηκε ή ότι ένα αρχείο εγκρίθηκε.

Το HTTPS προστατεύει τη μεταφορά, αλλά δεν αποδεικνύει ποιος δημιούργησε το payload. Η επαλήθευση υπογραφής συνδέει το ακριβές σώμα του request με ένα μυστικό που γνωρίζουν ο provider και ο παραλήπτης. Αποτελεί βασικό βήμα πριν από parsing, business logic ή enqueue.

01Πώς λειτουργεί μια HMAC υπογραφή

Ο provider υπολογίζει HMAC πάνω στο payload, συχνά με SHA-256 και ένα κοινό secret, και στέλνει το αποτέλεσμα σε header. Ο receiver υπολογίζει την αναμενόμενη υπογραφή με το δικό του αντίγραφο του secret και συγκρίνει τις δύο τιμές.

Αν το payload άλλαξε έστω και κατά έναν χαρακτήρα ή χρησιμοποιήθηκε άλλο secret, οι υπογραφές δεν ταιριάζουν. Η GitHub τεκμηρίωση, για παράδειγμα, περιγράφει HMAC digest στο X-Hub-Signature-256 και συνιστά validation πριν από περαιτέρω επεξεργασία.

02Χρησιμοποιήστε το raw request body

Η υπογραφή υπολογίζεται πάνω στα αρχικά bytes. Αν το framework κάνει πρώτα JSON parsing και μετά ξαναδημιουργήσει string, μπορεί να αλλάξει κενά, σειρά πεδίων ή escaping. Το JSON παραμένει σημασιολογικά ίδιο, αλλά η υπογραφή δεν θα ταιριάζει.

Η σωστή σειρά είναι:

Η middleware ρύθμιση πρέπει να ελεγχθεί ειδικά για το webhook route. Ένας global JSON parser μπορεί να έχει ήδη καταναλώσει ή μετασχηματίσει το body.

03Constant-time σύγκριση

Η απλή σύγκριση strings μπορεί να σταματά στο πρώτο διαφορετικό byte. Σε ορισμένα περιβάλλοντα, οι μικρές χρονικές διαφορές μπορούν να διαρρεύσουν πληροφορία για την αναμενόμενη τιμή.

Χρησιμοποιούμε timing-safe comparison της γλώσσας ή της crypto βιβλιοθήκης, αφού πρώτα ελέγξουμε ότι τα buffers έχουν συμβατό μήκος. Η GitHub προτείνει ρητά secure_compare ή crypto.timingSafeEqual αντί για απλό τελεστή ισότητας.

04Η υπογραφή δεν αποτρέπει από μόνη της το replay

Ένας attacker που καταγράψει ένα έγκυρο signed request μπορεί να το στείλει ξανά. Η υπογραφή θα εξακολουθεί να είναι σωστή, επειδή το payload δεν άλλαξε.

Για replay protection χρειάζονται:

• signed timestamp και μικρό tolerance window,
• μοναδικό delivery ή event ID,
• αποθήκευση των IDs που έχουν ήδη επεξεργαστεί,
• idempotent business operation.

Απορρίπτουμε requests με timestamp πολύ παλιό ή υπερβολικά μελλοντικό. Το delivery ID διατηρείται για διάστημα τουλάχιστον όσο το πιθανό redelivery window. Η ανοχή ώρας προϋποθέτει σωστό clock synchronization στους servers.

05Deduplication και idempotency είναι διαφορετικά

Το deduplication εντοπίζει ότι έχουμε ήδη δει συγκεκριμένο event. Η idempotency εξασφαλίζει ότι ακόμη κι αν το event περάσει δύο φορές, η επιχειρηματική πράξη δεν διπλασιάζεται.

Ένα unique constraint στο provider event ID μπορεί να αποτρέψει δεύτερη εγγραφή. Για πληρωμές ή fulfillments, χρησιμοποιούμε και σταθερό business key. Δεν βασιζόμαστε μόνο σε in-memory cache, επειδή χάνεται σε restart και δεν μοιράζεται απαραίτητα μεταξύ instances.

06Απαντήστε γρήγορα και επεξεργαστείτε ασύγχρονα

Μετά την επαλήθευση και την ασφαλή αποθήκευση του event, το endpoint επιστρέφει γρήγορα επιτυχία. Η βαριά εργασία εκτελείται από queue worker. Αν το endpoint περιμένει ERP, email και τρίτα APIs, ο provider μπορεί να θεωρήσει την παράδοση αποτυχημένη και να ξαναστείλει το event.

Η παραλαβή και η επεξεργασία έχουν ξεχωριστές καταστάσεις. Ένα 2xx σημαίνει ότι αποθηκεύσαμε με ασφάλεια το event, όχι απαραίτητα ότι ολοκληρώθηκαν όλες οι επόμενες ενέργειες.

07Validation μετά την αυθεντικότητα

Έγκυρη υπογραφή αποδεικνύει προέλευση και ακεραιότητα, όχι ότι το payload είναι κατάλληλο για την εφαρμογή. Ελέγχουμε event type, schema, υποχρεωτικά IDs, tenant mapping και επιτρεπόμενες μεταβάσεις κατάστασης.

Δεν εμπιστευόμαστε ποσά, ρόλους ή customer IDs χωρίς διασταύρωση όπου το use case απαιτεί. Σε κρίσιμες ροές μπορεί να ανακτούμε το αντικείμενο από το επίσημο API του provider με το δικό μας credential.

08Secret storage και rotation

Το webhook secret αποθηκεύεται σε secret manager ή ασφαλή environment variable, όχι στον κώδικα ή στα logs. Διαφορετικά environments και providers χρειάζονται διαφορετικά secrets, ώστε μια διαρροή να έχει περιορισμένο εύρος.

Για rotation υποστηρίζουμε προσωρινά current και previous secret. Επαληθεύουμε πρώτα με το νέο και έπειτα με το παλιό για μικρό, ελεγχόμενο διάστημα. Παρακολουθούμε ποιο secret επαλήθευσε κάθε event, χωρίς να καταγράφουμε την τιμή του, και αφαιρούμε το παλιό μόλις ολοκληρωθεί η μετάβαση.

09Πολλά accounts και tenants

Σε SaaS integrations, κάθε πελάτης μπορεί να έχει διαφορετικό webhook secret. Το endpoint πρέπει να επιλέξει υποψήφιο secret χωρίς να εμπιστευτεί μη υπογεγραμμένο tenant ID με τρόπο που επιτρέπει enumeration.

Χρησιμοποιούμε route identifier, endpoint ID ή ασφαλές mapping που έχει ορίσει ο provider. Περιορίζουμε τον αριθμό δοκιμών υπογραφής και δεν επιστρέφουμε λεπτομέρειες που αποκαλύπτουν αν υπάρχει συγκεκριμένος tenant.

10IP allowlists: πρόσθετο φίλτρο, όχι υποκατάστατο

Αν ο provider δημοσιεύει σταθερές IP ranges, ένα allowlist μπορεί να μειώσει ανεπιθύμητη κίνηση. Δεν αντικαθιστά την υπογραφή: ranges αλλάζουν, proxies επηρεάζουν τη διεύθυνση και ένα δίκτυο provider δεν ταυτοποιεί το συγκεκριμένο account.

Η χρήση mTLS μπορεί να προσθέσει ισχυρή ταυτότητα μεταφοράς σε enterprise integrations, αλλά η application-level idempotency και event validation παραμένουν απαραίτητες.

11Logging χωρίς διαρροή

Καταγράφουμε delivery ID, event type, provider, verification result, timestamp delta, HTTP status και processing state. Δεν καταγράφουμε secrets, authorization headers ή ολόκληρα payloads με προσωπικά και οικονομικά δεδομένα.

Τα invalid signatures μετρώνται και περιορίζονται. Η απάντηση παραμένει γενική, ενώ οι εσωτερικές λεπτομέρειες πηγαίνουν σε προστατευμένο log και alert όταν το pattern είναι ασυνήθιστο.

12Πώς το υλοποιεί η Ai Foundry

13Checklist

Ένα ασφαλές webhook δεν είναι απλώς route που δέχεται JSON. Είναι ελεγχόμενη είσοδος σε επιχειρηματικές ενέργειες, με απόδειξη προέλευσης και προστασία από επανάληψη.

14Πηγές

Γράφτηκε από την ομάδα της Ai Foundry (aifoundry.gr), εταιρείας ανάπτυξης λογισμικού και εφαρμογών τεχνητής νοημοσύνης στην Ελλάδα.