Τι είναι το webhook; Πώς οι εφαρμογές ειδοποιούν η μία την άλλη

Ένα webhook είναι ένα αυτόματο μήνυμα που στέλνει μια υπηρεσία στην εφαρμογή σου τη στιγμή που συμβαίνει κάτι. Όταν μια πληρωμή πελάτη επιτυγχάνει, το Stripe στέλνει ένα webhook σε μια διεύθυνση της εφαρμογής σου που λέει «η πληρωμή ολοκληρώθηκε, εδώ είναι τα στοιχεία», και η εφαρμογή σου αντιδρά — σημειώνει την παραγγελία ως πληρωμένη, στέλνει την απόδειξη, ξεκλειδώνει τον λογαριασμό. Με απλά λόγια: ένα API είναι η εφαρμογή σου που κάνει μια ερώτηση σε άλλη υπηρεσία· ένα webhook είναι η άλλη υπηρεσία που καλεί την εφαρμογή σου για να της πει κάτι.

Γιατί έχει σημασία όταν φτιάχνεις με AI

Μόλις η εφαρμογή σου δέχεται πληρωμές, λαμβάνει υποβολές φορμών από άλλο εργαλείο ή συνδέεται με υπηρεσίες όπως το GitHub, το Shopify ή ένα ημερολόγιο, θα συναντήσεις webhooks. Συνήθως είναι ο σωστός τρόπος να μάθεις ότι κάτι συνέβη — αλλά εκεί ακριβώς οι εφαρμογές που φτιάχνονται με AI συχνά κάνουν λάθος, με λεπτό τρόπο:

• Το endpoint δέχεται οποιοδήποτε αίτημα, οπότε κάποιος μπορεί να προσποιηθεί γεγονός «η πληρωμή πέτυχε».
• Η εφαρμογή δίνει πρόσβαση στη σελίδα επιστροφής του checkout αντί στο webhook, οπότε όσοι κλείνουν νωρίς την καρτέλα δεν παίρνουν ό,τι πλήρωσαν, και όσοι βρουν το URL επιτυχίας το παίρνουν δωρεάν.
• Το ίδιο γεγονός φτάνει δύο φορές και ο πελάτης παίρνει δύο παραγγελίες ή δύο email.

Ο τρόπος λειτουργίας των webhooks σού επιτρέπει να ζητάς τις προστασίες από την αρχή.

Μια καθημερινή αναλογία: το μήνυμα παράδοσης

Μπορείς να μάθεις αν ήρθε το δέμα σου με δύο τρόπους. Μπορείς να πηγαίνεις στην εξώπορτα κάθε δέκα λεπτά για να ελέγχεις (αυτό είναι το polling — η εφαρμογή σου καλεί επανειλημμένα ένα API για να ρωτήσει «κάτι καινούργιο;»). Ή ο courier μπορεί να σου στείλει μήνυμα όταν παραδώσει.

Το μήνυμα είναι σαφώς καλύτερο — αρκεί να μπορείς να το εμπιστευτείς. Αν όποιος μπορεί να σου στείλει μήνυμα «παραδόθηκε», θέλεις κάποιον τρόπο να ξέρεις ότι ήρθε όντως από τον courier. Και αν το τηλέφωνό σου ήταν κλειστό όταν ήρθε το μήνυμα, θέλεις ο courier να ξαναδοκιμάσει αργότερα. Αυτές οι δύο ανησυχίες — επαλήθευση και επαναδοκιμές — είναι το μεγαλύτερο μέρος αυτού που κάνει τα webhooks δύσκολα.

Πώς λειτουργεί ένα webhook, βήμα προς βήμα

1. Δημιουργείς ένα endpoint στο backend της εφαρμογής σου: ένα URL όπως https://yourapp.com/webhooks/stripe που δέχεται αιτήματα POST.
2. Καταχωρείς αυτό το URL στον πάροχο και επιλέγεις ποια γεγονότα θέλεις (για παράδειγμα, «ολοκληρώθηκε checkout» και «ακυρώθηκε συνδρομή»).
3. Ο πάροχος σου δίνει ένα μυστικό υπογραφής. Το αποθηκεύεις ως μυστικό στον server σου — δες μεταβλητές περιβάλλοντος και μυστικά.
4. Συμβαίνει ένα γεγονός. Ο πάροχος στέλνει ένα αίτημα HTTP στο URL σου με σώμα JSON που το περιγράφει, μαζί με μια κεφαλίδα υπογραφής.
5. Η εφαρμογή σου επαληθεύει την υπογραφή, καταγράφει το ID του γεγονότος, απαντά γρήγορα με κωδικό επιτυχίας (200), και μετά κάνει τη δουλειά.
6. Αν η εφαρμογή σου δεν απαντήσει με επιτυχία, πολλοί πάροχοι προσπαθούν ξανά αργότερα.

Υπογραφές

Μια υπογραφή αποδεικνύει ότι το αίτημα ήρθε από τον πάροχο και δεν άλλαξε. Το Stripe, για παράδειγμα, υπολογίζει ένα HMAC (ένα είδος κλειδωμένου αποτυπώματος) με SHA-256 πάνω στο σώμα του αιτήματος και σε μια χρονική σήμανση, χρησιμοποιώντας το μυστικό υπογραφής, και το στέλνει σε μια κεφαλίδα Stripe-Signature. Η εφαρμογή σου κάνει τον ίδιο υπολογισμό με το δικό της αντίγραφο του μυστικού· αν τα αποτελέσματα ταιριάζουν, το αίτημα είναι γνήσιο. Επειδή και η χρονική σήμανση υπογράφεται, μπορείς να απορρίψεις παλιά αιτήματα που κάποιος κατέγραψε και ξαναστέλνει αργότερα — οι βιβλιοθήκες του Stripe έχουν προεπιλεγμένη ανοχή πέντε λεπτών, σύμφωνα με την τεκμηρίωσή του από τον Σεπτέμβριο 2026.

Μια πρακτική λεπτομέρεια: η υπογραφή υπολογίζεται στο ακατέργαστο σώμα του αιτήματος. Αν το framework σου αναλύσει και ξαναμορφοποιήσει το JSON πριν τον έλεγχο, ο έλεγχος αποτυγχάνει. Αυτό είναι ένα πολύ συνηθισμένο σφάλμα.

Επαναδοκιμές, διπλότυπα και σειρά

Οι πάροχοι διαφέρουν, γι' αυτό έλεγξε την τεκμηρίωση κάθε ενός. Από τον Σεπτέμβριο 2026:

Η τεκμηρίωση του Stripe λέει επίσης ότι τα γεγονότα δεν έχουν εγγυημένα να φτάσουν με τη σειρά που συνέβησαν, και ότι το ίδιο γεγονός μπορεί περιστασιακά να φτάσει περισσότερες από μία φορές, γι' αυτό προτείνει να καταγράφεις τα ID των γεγονότων.

Το γενικό δίδαγμα ισχύει για κάθε πάροχο: τα γεγονότα μπορεί να φτάσουν καθυστερημένα, περισσότερες από μία φορά και εκτός σειράς. Ο χειριστής σου πρέπει να είναι ιδεμπότεντ — η επεξεργασία του ίδιου γεγονότος δύο φορές έχει το ίδιο αποτέλεσμα με μία.

Ένα παράδειγμα βήμα προς βήμα: ξεκλείδωμα ενός επί πληρωμή μαθήματος

Πουλάς ένα διαδικτυακό μάθημα. Ένας μαθητής πατά Αγορά, πληρώνει στη φιλοξενούμενη σελίδα checkout του Stripe και επιστρέφει στον ιστότοπό σου.

Ο εύθραυστος τρόπος: η σελίδα «ευχαριστούμε» ξεκλειδώνει το μάθημα. Αν ο μαθητής κλείσει τον browser κατά την ανακατεύθυνση, πλήρωσε αλλά δεν έχει πρόσβαση. Αν κάποιος μαντέψει το URL της σελίδας ευχαριστιών, αποκτά πρόσβαση χωρίς να πληρώσει.

Ο τρόπος με webhook:

1. Όταν το Stripe επιβεβαιώσει την πληρωμή, στέλνει γεγονός checkout.session.completed στο /webhooks/stripe.
2. Το backend σου επαληθεύει την υπογραφή με το μυστικό. Αν αποτύχει, απαντά 400 και δεν κάνει τίποτα.
3. Ελέγχει αν αυτό το ID γεγονότος έχει ήδη επεξεργαστεί. Αν ναι, απαντά 200 και σταματά.
4. Αποθηκεύει το ID του γεγονότος, απαντά 200, και μετά δίνει στον μαθητή πρόσβαση και στέλνει email καλωσορίσματος.
5. Η σελίδα ευχαριστιών απλώς λέει «Η πληρωμή ελήφθη — το μάθημά σου θα εμφανιστεί σε λίγο» και ελέγχει την κατάσταση πρόσβασης του μαθητή.

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

Βασικοί όροι

• Endpoint: το URL της εφαρμογής σου που λαμβάνει τα webhooks.
• Γεγονός / payload: τι συνέβη, και τα δεδομένα που το περιγράφουν (συνήθως JSON).
• Μυστικό υπογραφής: το κοινό μυστικό που χρησιμοποιείται για την επαλήθευση των υπογραφών.
• Ιδεμπότεντ (idempotent): ασφαλές να τρέξει περισσότερες από μία φορές με το ίδιο αποτέλεσμα.
• Polling: επαναλαμβανόμενη ερώτηση σε ένα API για αλλαγές αντί να περιμένεις webhook.
• Tunnel: εργαλείο που δίνει στο laptop ένα προσωρινό δημόσιο URL ώστε τα webhooks να το φτάνουν κατά την ανάπτυξη.

Συνηθισμένα λάθη και παρανοήσεις

• Να μην επαληθεύεις τις υπογραφές. Το URL του endpoint δεν είναι μυστικό. Η επαλήθευση είναι αυτό που κάνει το αίτημα αξιόπιστο.
• Να κάνεις αργή δουλειά πριν απαντήσεις. Το να στέλνεις email ή να δημιουργείς PDF πριν απαντήσεις μπορεί να προκαλέσει timeouts, που προκαλούν επαναδοκιμές, που προκαλούν διπλότυπα.
• Να υποθέτεις ακριβώς μία φορά, με σειρά. Κατέγραψε τα ID των γεγονότων και μην βασίζεσαι στη σειρά άφιξης.
• Να χρησιμοποιείς URL προεπισκόπησης. Τα webhooks χρειάζονται σταθερή, δημόσια διεύθυνση. Οι ιδιωτικές προεπισκοπήσεις και το localhost δεν είναι προσβάσιμες από το internet· χρησιμοποίησε το δημοσιευμένο URL σου (ή tunnel κατά τις δοκιμές).
• Ανάμειξη μυστικών δοκιμής και κανονικής λειτουργίας. Οι πάροχοι συχνά εκδίδουν διαφορετικά μυστικά υπογραφής για λειτουργία δοκιμής και κανονική. Αποθήκευσε και τα δύο και χρησιμοποίησε το σωστό.
• Να εμπιστεύεσαι τυφλά το payload για σημαντικές αποφάσεις. Για ενέργειες υψηλού διακυβεύματος, είναι λογικό να φέρεις την τελευταία κατάσταση από το API του παρόχου αφού λάβεις το γεγονός.

Τι να ζητήσεις από τον AI builder σου

Πρόσθεσε ένα endpoint POST /webhooks/stripe στον server. Επαλήθευσε την υπογραφή του Stripe χρησιμοποιώντας το ακατέργαστο σώμα του αιτήματος και το μυστικό STRIPE_WEBHOOK_SECRET. Απόρριψε τις άκυρες υπογραφές με 400. Αποθήκευσε κάθε ID γεγονότος και παράλειψε τα γεγονότα που έχουν ήδη επεξεργαστεί. Απάντησε 200 γρήγορα, και μετά χειρίσου το checkout.session.completed σημειώνοντας την παραγγελία ως πληρωμένη και στέλνοντας την απόδειξη. Κατέγραψε τον τύπο του γεγονότος. Μη δίνεις πρόσβαση από τη σελίδα επιτυχίας του checkout.

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

Webhooks στο Mythex

Το Mythex δεν διαθέτει ξεχωριστή υπηρεσία webhooks· ζητάς από τον agent να προσθέσει ένα endpoint webhook στο δικό backend της εφαρμογής σου, και δείχνεις τον πάροχο στο δημοσιευμένο URL σου, αφού τα webhooks χρειάζονται δημόσια διεύθυνση. Το μυστικό υπογραφής μπαίνει στα μυστικά του project σου, και αν το αλλάξεις σε ζωντανή εφαρμογή, δημοσίευσε ξανά. Η συνταγή της τεκμηρίωσης για τον χειρισμό webhooks έχει έτοιμο prompt, και τα πρότυπα καταστημάτων είναι καλό σημείο εκκίνησης για εφαρμογές που δέχονται πληρωμές.

Ερωτήσεις