Τι πρέπει να επιστρέφει ένα endpoint webhook παρακολούθησης; Κωδικοί κατάστασης, χρονικά όρια και επαναπροσπάθειες;
Ένα endpoint webhook παρακολούθησης θα πρέπει να επιστρέφει μια γρήγορη, σκόπιμη απόκριση 2xx αφού αποδεχτεί το συμβάν για επεξεργασία. Στις περισσότερες ενσωματώσεις, το ασφαλέστερο μοτίβο είναι να γίνει έλεγχος ταυτότητας του αιτήματος, επικύρωση του payload, αποθήκευση ή τοποθέτηση του συμβάντος σε ουρά και επιβεβαίωσή του με 200 OK ή 202 Accepted. Χρησιμοποιήστε αποκρίσεις 4xx για αιτήματα που ο αποστολέας δεν θα πρέπει να επαναλάβει και αποκρίσεις 5xx όταν ένα προσωρινό πρόβλημα στην πλευρά του διακομιστή απέτρεψε την αποδοχή. Η ακριβής συμπεριφορά σχετικά με το timeout και τις επαναλήψεις εξακολουθεί να εξαρτάται από το συμβόλαιο του παρόχου webhook, επομένως η υλοποίησή σας θα πρέπει να σχεδιαστεί με βάση την τεκμηριωμένη συμπεριφορά του αποστολέα και όχι υποθέσεις.
Για ένα webhook παρακολούθησης ή κατάστασης αποστολής, αυτή η διάκριση έχει σημασία επειδή τα συμβάντα παράδοσης μπορεί να φτάσουν περισσότερες από μία φορές, εκτός σειράς ή να επαναληφθούν μετά από αποτυχία δικτύου. Η δουλειά του endpoint δεν είναι απαραίτητα να ολοκληρώνει κάθε επιχειρησιακή λειτουργία πριν απαντήσει. Η πρώτη του δουλειά είναι να λαμβάνει μια αξιόπιστη απόφαση σχετικά με το αν το συμβάν έχει γίνει αποδεκτό.
Το συμβόλαιο απόκρισης στην πράξη
Μια απόκριση webhook έχει δύο αποδέκτες: το σύστημα αποστολής και τη δική σας εφαρμογή. Ο αποστολέας χρειάζεται ένα σαφές αποτέλεσμα HTTP ώστε να αποφασίσει αν θα σημειώσει την παράδοση ως επιτυχή, αν θα την επαναλάβει ή αν θα σταματήσει. Η εφαρμογή σας χρειάζεται αρκετό χρόνο για να επαληθεύσει και να καταγράψει μόνιμα το συμβάν. Αυτοί οι στόχοι είναι ευκολότερο να επιτευχθούν όταν το endpoint διαθέτει μια μικρή σύγχρονη διαδρομή και μια ξεχωριστή ασύγχρονη διαδρομή επεξεργασίας.
- Λάβετε το αίτημα HTTP μέσω HTTPS.
- Ελέγξτε την υπογραφή, τα διαπιστευτήρια ελέγχου ταυτότητας, τη χρονική σήμανση ή άλλους ελέγχους ακεραιότητας του αιτήματος που απαιτεί ο πάροχος.
- Αναλύστε και επικυρώστε το payload χωρίς να εκτελείτε αργές εργασίες σε εξαρτώμενα συστήματα.
- Εγγράψτε το συμβάν ή μια εγγραφή αποτροπής διπλοτύπων και αναφορά συμβάντος σε μόνιμη αποθήκευση ή αξιόπιστη ουρά.
- Επιστρέψτε μια σκόπιμη απόκριση 2xx.
- Επεξεργαστείτε ασύγχρονα την ενημέρωση παρακολούθησης, την ειδοποίηση πελάτη, την αλλαγή αποθέματος ή άλλη επιχειρησιακή ενέργεια.
Μια απόκριση δεν θα πρέπει να δηλώνει αποδοχή αν το συμβάν υπάρχει μόνο στη μνήμη της διεργασίας. Αν η εφαρμογή καταρρεύσει αμέσως μετά την επιστροφή επιτυχίας, ένα συμβάν που δεν αποθηκεύτηκε ποτέ μπορεί να χαθεί, ενώ ο αποστολέας πιστεύει ότι η παράδοση ολοκληρώθηκε επιτυχώς. Επομένως, το σημείο στο οποίο επιστρέφετε 2xx θα πρέπει να αντιστοιχεί στην πραγματική εγγύηση μονιμότητας που παρέχετε.
Ποιον κωδικό κατάστασης πρέπει να επιστρέφει ένα webhook;
| Απόκριση | Σημασία για τον αποστολέα | Τυπική χρήση webhook |
|---|---|---|
200 OK | Το αίτημα έγινε αποδεκτό και υποβλήθηκε σε επιτυχή επεξεργασία. | Πρακτική προεπιλογή μετά την επικύρωση και τη μόνιμη αποδοχή. |
202 Accepted | Το αίτημα έγινε αποδεκτό για επεξεργασία, αλλά η εργασία μπορεί να συνεχιστεί. | Χρήσιμο όταν το συμβάν έχει τοποθετηθεί με ασφάλεια σε ουρά, αλλά η επιχειρησιακή επεξεργασία είναι ασύγχρονη. |
204 No Content | Το αίτημα ολοκληρώθηκε επιτυχώς και δεν απαιτείται σώμα απόκρισης. | Κατάλληλο όταν ο πάροχος αποδέχεται κενή απόκριση επιτυχίας. |
400–499 | Το αίτημα είναι μη έγκυρο, μη εξουσιοδοτημένο ή μη αποδεκτό όπως στάλθηκε. | Λανθασμένο payload, αποτυχία ελέγχου ταυτότητας, μη έγκυρη υπογραφή ή συμβάν που απορρίφθηκε οριστικά. |
429 Too Many Requests | Ο παραλήπτης εφαρμόζει περιορισμό ρυθμού. | Χρησιμοποιήστε το μόνο όταν η συμπεριφορά επανάληψης του αποστολέα και η πολιτική περιορισμού ρυθμού σας είναι συμβατές. |
500–599 | Ο παραλήπτης δεν μπόρεσε να αποδεχτεί το αίτημα λόγω προβλήματος στον διακομιστή ή προσωρινού προβλήματος. | Διακοπή βάσης δεδομένων, αποτυχία ουράς, αποτυχία εξάρτησης ή απροσδόκητο σφάλμα εφαρμογής. |
200 OK είναι συχνά η λιγότερο απρόσμενη επιλογή, επειδή είναι ευρέως κατανοητό ως επιτυχής λήψη. Το 202 Accepted είναι επίσης σημασιολογικά χρήσιμο όταν το endpoint έχει αποδεχτεί το συμβάν για μεταγενέστερη επεξεργασία. Κανένας από τους δύο κωδικούς δεν είναι αυτόματα σωστός: η τεκμηρίωση του αποστολέα μπορεί να καθορίζει ποιες αποκρίσεις 2xx θεωρούνται επιτυχείς και ορισμένοι πάροχοι μπορεί να απαιτούν συγκεκριμένο σώμα ή τύπο περιεχομένου.
Μην επιστρέφετε απόκριση 2xx απλώς επειδή το αίτημα HTTP έφτασε στον διακομιστή σας. Αν η επαλήθευση της υπογραφής αποτύχει ή το payload δεν μπορεί να ερμηνευτεί με ασφάλεια, μια απόκριση 4xx είναι συνήθως πιο ακριβής. Αντίθετα, μην επιστρέφετε 4xx για προσωρινή διακοπή της βάσης δεδομένων, αν το συμβάν θα μπορούσε να ολοκληρωθεί αργότερα. Μια απόκριση 5xx δίνει σε έναν αποστολέα που υποστηρίζει επαναλήψεις την ευκαιρία να παραδώσει ξανά το συμβάν, αν και ο πάροχος μπορεί να εφαρμόζει τη δική του πολιτική.
Πώς πρέπει να αντιμετωπίζονται τα timeouts;
Οι τιμές timeout των webhook είναι ειδικές για κάθε πάροχο. Δεν υπάρχει καθολικό timeout HTTP που να χρησιμοποιείται από κάθε πλατφόρμα παρακολούθησης και ένας αποστολέας μπορεί να σταματήσει να περιμένει πριν ολοκληρώσει η εφαρμογή σας μια αργή λειτουργία. Αντιμετωπίστε το τεκμηριωμένο timeout του αποστολέα ως ανώτατο όριο και όχι ως στόχο. Το endpoint σας θα πρέπει κανονικά να απαντά αρκετά πριν από αυτό το όριο.
Το συνηθέστερο σχεδιαστικό λάθος είναι η εκτέλεση όλης της εργασίας σε εξαρτώμενα συστήματα πριν από την επιβεβαίωση του webhook. Ένας handler μπορεί να καλέσει διαδοχικά μια βάση δεδομένων, ένα σύστημα διαχείρισης παραγγελιών, μια υπηρεσία ειδοποιήσεων και μια διοχέτευση αναλυτικών στοιχείων. Μία αργή εξάρτηση μπορεί να κάνει τον αποστολέα να δει timeout, παρότι η εφαρμογή σας τελικά ολοκληρώνει την εργασία. Τότε ο αποστολέας μπορεί να επαναλάβει το αίτημα, δημιουργώντας διπλή επεξεργασία ή ανταγωνιστικές ενημερώσεις.
Περιορίστε τη σύγχρονη διαδρομή μόνο στην εργασία που απαιτείται για μια ασφαλή απόφαση αποδοχής. Αυτό συνήθως περιλαμβάνει έλεγχο ταυτότητας αιτήματος, βασική επικύρωση σχήματος, μόνιμη αποθήκευση συμβάντος και δημοσίευση στην ουρά. Τοποθετήστε τον δαπανηρό εμπλουτισμό, τις αναζητήσεις μεταφορέων, την ανταλλαγή μηνυμάτων με πελάτες και τις κλήσεις API τρίτων πίσω από έναν worker. Παρακολουθείτε ξεχωριστά τον χρόνο λήψης, επικύρωσης, μόνιμης αποθήκευσης και επιβεβαίωσης του συμβάντος από τον χρόνο επεξεργασίας του.
Ένα timeout δεν είναι το ίδιο με μια αποτυχημένη επιχειρησιακή λειτουργία. Από την πλευρά του αποστολέα, ένα timeout συνήθως σημαίνει ότι δεν έλαβε αξιοποιήσιμη απόκριση επιτυχίας. Η υπηρεσία σας μπορεί να είχε αποθηκεύσει επιτυχώς το συμβάν λίγο πριν κλείσει η σύνδεση. Γι’ αυτό απαιτούνται idempotency και αποτροπή διπλοτύπων, ακόμη και όταν το endpoint φαίνεται αξιόπιστο.
Τι προκαλεί τις επαναλήψεις;
Ένας αποστολέας webhook μπορεί να επαναλάβει την αποστολή μετά από σφάλμα σύνδεσης, timeout ή απόκριση που το συμβόλαιό του ταξινομεί ως ανεπιτυχή. Το ακριβές χρονοδιάγραμμα, ο μέγιστος αριθμός προσπαθειών, ο αλγόριθμος backoff και το παράθυρο παράδοσης διαφέρουν ανά πάροχο. Μην υπόσχεστε συγκεκριμένο αριθμό επαναλήψεων, εκτός αν αναφέρεται στην τεκμηρίωση του παρόχου.
Ο παραλήπτης θα πρέπει να θεωρεί ότι μπορούν να συμβούν επαναλήψεις και να σχεδιάζει σκόπιμα για αυτές:
- Χρησιμοποιήστε ένα αναγνωριστικό συμβάντος όταν είναι διαθέσιμο. Αποθηκεύστε το με μοναδικό περιορισμό ή ισοδύναμο κλειδί αποτροπής διπλοτύπων.
- Κάντε την επεξεργασία idempotent. Η εφαρμογή της ίδιας ενημέρωσης κατάστασης παράδοσης δύο φορές δεν θα πρέπει να στέλνει δύο μηνύματα πελατών, να δημιουργεί δύο επιστροφές χρημάτων ή να προωθεί λανθασμένα μια παραγγελία.
- Διατηρήστε το αρχικό payload ή μια χρήσιμη εγγραφή ελέγχου. Αυτό υποστηρίζει την επανάληψη, τη διερεύνηση και τη συμφωνία.
- Διαχωρίστε την αποδοχή από την επεξεργασία. Ένας worker μπορεί να επαναλάβει εσωτερικές αποτυχίες χωρίς να αναγκάζει τον αποστολέα να επαναλάβει ολόκληρη την ανταλλαγή HTTP.
- Καταγράφετε τους κωδικούς απόκρισης και την καθυστέρηση. Η αύξηση των αποκρίσεων 5xx, των timeout ή των διπλότυπων αναγνωριστικών συμβάντων μπορεί να αποκαλύψει διακοπή λειτουργίας πριν οι χρήστες αναφέρουν ελλείπουσες ενημερώσεις παρακολούθησης.
Ένα διπλότυπο συμβάν θα πρέπει συνήθως να λαμβάνει επιτυχή απόκριση αν το αρχικό συμβάν είχε ήδη γίνει μόνιμα αποδεκτό. Η επιστροφή σφάλματος για κάθε διπλότυπο μπορεί να προκαλέσει περιττές επαναλήψεις. Το endpoint μπορεί να καταγράψει ότι το συμβάν είχε ήδη εμφανιστεί, να παραλείψει την επαναλαμβανόμενη επιχειρησιακή ενέργεια και να επιστρέψει την ίδια κατηγορία επιτυχίας που χρησιμοποιείται για ένα νέο αποδεκτό συμβάν.
Πότε πρέπει να επιστρέφετε 4xx, 429 ή 5xx;
Επιστρέψτε 4xx όταν η επανάληψη του ίδιου αιτήματος είναι απίθανο να διορθώσει το πρόβλημα. Παραδείγματα είναι μια μη έγκυρη υπογραφή, έλλειψη απαιτούμενου ελέγχου ταυτότητας, μη υποστηριζόμενη μορφή payload ή αίτημα που παραβιάζει έναν μόνιμο κανόνα επικύρωσης. Πριν επιλέξετε 4xx, ελέγξτε αν ο αποστολέας αντιμετωπίζει αυτή την κατάσταση ως μόνιμη αποτυχία. Ορισμένες πλατφόρμες έχουν δικούς τους κανόνες για τις αποτυχημένες παραδόσεις.
Χρησιμοποιήστε το 429 με προσοχή. Το HTTP ορίζει το 429 για περιορισμό ρυθμού και η κεφαλίδα Retry-After μπορεί να ενημερώσει πότε ενδέχεται να είναι κατάλληλη μια επανάληψη. Ωστόσο, δεν ερμηνεύουν όλοι οι αποστολείς webhook το 429 με τον ίδιο τρόπο. Αν η ουρά σας είναι γεμάτη ή η υπηρεσία σας υπερφορτωμένη, επιβεβαιώστε ότι ο πάροχος θα επαναλάβει με ασφάλεια και ότι το χρονοδιάγραμμα επαναλήψεων δεν θα επιδεινώσει την υπερφόρτωση. Μια ουρά εισόδου με όριο και ένα σχέδιο backpressure είναι συνήθως καλύτερα από το να επιτρέπετε την απρόβλεπτη αποτυχία αιτημάτων.
Επιστρέψτε 5xx όταν ο παραλήπτης δεν μπορεί να αποδεχτεί με ασφάλεια το συμβάν λόγω προσωρινού προβλήματος. Αυτό περιλαμβάνει μη διαθέσιμη βάση δεδομένων, αποτυχία εγγραφής σε μόνιμη ουρά ή εσωτερικό σφάλμα που εμπόδισε την επικύρωση ή τη μόνιμη αποθήκευση. Η επιστροφή 200 ενώ απορρίπτετε σιωπηρά το συμβάν δυσκολεύει την ανάκτηση, επειδή ο αποστολέας δεν έχει λόγο να προσπαθήσει ξανά.
Αποφύγετε την εξάρτηση από ανακατευθύνσεις όπως 301, 302 ή 307 για την παράδοση webhook. Η διαχείριση ανακατευθύνσεων διαφέρει μεταξύ πελατών και η ανακατεύθυνση ενός υπογεγραμμένου αιτήματος μπορεί να δημιουργήσει ασάφεια σχετικά με τον προορισμό, τη μέθοδο και το σώμα. Ρυθμίστε τον πάροχο με το τελικό endpoint HTTPS.
Μια αξιόπιστη πολιτική απόκρισης για συμβάντα παρακολούθησης
Για τις περισσότερες ενσωματώσεις webhook παρακολούθησης, η ακόλουθη πολιτική αποτελεί λογικό σημείο εκκίνησης:
- Επιστρέψτε
200ή202αφού το συμβάν περάσει τον έλεγχο ταυτότητας και αποθηκευτεί μόνιμα ή τοποθετηθεί σε αξιόπιστη ουρά. - Επιστρέψτε απόκριση 4xx για μη έγκυρη υπογραφή, μη έγκυρο έλεγχο ταυτότητας ή payload που δεν μπορεί να χρησιμοποιηθεί μόνιμα, σύμφωνα με τους τεκμηριωμένους κανόνες του παρόχου.
- Επιστρέψτε 5xx όταν μια προσωρινή αποτυχία εμποδίζει τη μόνιμη αποδοχή.
- Επιστρέψτε επιτυχή απόκριση για ένα με ασφάλεια αναγνωρισμένο διπλότυπο, αποτρέποντας παράλληλα τα διπλότυπα επιχειρησιακά αποτελέσματα.
- Διατηρήστε τον handler γρήγορο και μετρήστε την καθυστέρηση επιβεβαίωσής του.
- Δοκιμάστε σενάρια timeout, επανάληψης, διπλοτύπων, εκτός σειράς, λανθασμένων δεδομένων και διακοπής λειτουργίας του παρόχου πριν από την έναρξη παραγωγικής λειτουργίας.
Αν ενσωματώνετε ένα tracking API, ξεκινήστε από την τεκμηρίωση webhook του παρόχου και επιβεβαιώστε τους αποδεκτούς κωδικούς επιτυχίας, τη μέθοδο υπογραφής αιτημάτων, το timeout, τις συνθήκες επανάληψης, το σχήμα payload και το αναγνωριστικό συμβάντος. Για ενσωματώσεις 17TRACK, η επίσημη τεκμηρίωση Tracking API είναι το κατάλληλο μέρος για την επαλήθευση του συμβολαίου του συγκεκριμένου παρόχου, αντί να το συμπεραίνετε από τη γενική πρακτική HTTP.
Λίστα ελέγχου υλοποίησης
- Το endpoint είναι προσβάσιμο μέσω HTTPS και διαθέτει σταθερό URL παραγωγής.
- Ο έλεγχος ταυτότητας και η επαλήθευση υπογραφής πραγματοποιούνται πριν από την επιχειρησιακή επεξεργασία.
- Το ακατέργαστο αίτημα ή μια επαληθεύσιμη αναπαράστασή του διατηρείται όπου απαιτείται για ελέγχους υπογραφής και αντιμετώπιση προβλημάτων.
- Το συμβάν αποθηκεύεται μόνιμα πριν σταλεί η απόκριση επιτυχίας.
- Οι διπλότυπες παραδόσεις είναι ασφαλείς και δεν επαναλαμβάνουν μη αναστρέψιμες ενέργειες.
- Οι workers μπορούν να επαναλάβουν την εσωτερική επεξεργασία ανεξάρτητα από τον κύκλο επανάληψης HTTP του αποστολέα.
- Τα αρχεία καταγραφής περιλαμβάνουν αναγνωριστικό συμβάντος, χρόνο παράδοσης, κωδικό απόκρισης, κατάσταση επεξεργασίας και αναγνωριστικό συσχέτισης χωρίς να εκθέτουν μυστικά.
- Οι ειδοποιήσεις διακρίνουν τα timeout endpoint, τις αποτυχίες επικύρωσης 4xx, τις διακοπές λειτουργίας 5xx, τις καθυστερήσεις ουράς και τις διπλότυπες παραδόσεις.
- Η τεκμηριωμένη συμπεριφορά του παρόχου έχει δοκιμαστεί με πραγματικά ή sandbox συμβάντα.
Συχνές ερωτήσεις
Είναι το 200 OK καλύτερο από το 202 Accepted για ένα webhook;
Κανένα από τα δύο δεν είναι καθολικά καλύτερο. Χρησιμοποιήστε 200 OK όταν το αίτημα έχει γίνει αποδεκτό και η ενσωμάτωσή σας αντιμετωπίζει την απόκριση ως γενική επιτυχία. Χρησιμοποιήστε 202 Accepted όταν το συμβάν έχει γίνει αποδεκτό για ασύγχρονη επεξεργασία. Επιβεβαιώστε ότι ο αποστολέας ταξινομεί την επιλεγμένη απόκριση 2xx ως επιτυχή.
Πρέπει ένα endpoint webhook να περιμένει μέχρι να ολοκληρωθεί πλήρως η επεξεργασία της ενημέρωσης παρακολούθησης;
Συνήθως όχι. Θα πρέπει να περιμένει μόνο μέχρι να γίνει έλεγχος ταυτότητας, επικύρωση και μόνιμη αποδοχή του συμβάντος. Η εργασία μεγάλης διάρκειας θα πρέπει κανονικά να πραγματοποιείται μετά την επιβεβαίωση, ώστε μια αργή εξάρτηση να μην προκαλεί αποφεύξιμο timeout και επανάληψη.
Τι πρέπει να συμβεί όταν το ίδιο συμβάν παρακολούθησης φτάσει δύο φορές;
Αναγνωρίστε το χρησιμοποιώντας το αναγνωριστικό συμβάντος του παρόχου ή ένα προσεκτικά σχεδιασμένο ισοδύναμο κλειδί, παραλείψτε τα διπλότυπα παρενέργειας και επιστρέψτε επιτυχή απόκριση αν το συμβάν είχε ήδη γίνει αποδεκτό. Έτσι οι επαναλήψεις είναι ασφαλείς χωρίς να αποκρύπτονται νέες αποτυχίες επεξεργασίας.
Μια μη έγκυρη υπογραφή πρέπει να επιστρέφει 400 ή 401;
Η επιλογή εξαρτάται από το μοντέλο ελέγχου ταυτότητας και τις τεκμηριωμένες προσδοκίες του παρόχου. Και τα δύο μπορούν να επικοινωνήσουν απόρριψη, αλλά η συνέπεια είναι σημαντικότερη από την καθολική επιλογή ενός κωδικού. Μην επιβεβαιώνετε ένα συμβάν του οποίου την αυθεντικότητα δεν μπορείτε να επαληθεύσετε.
Μια απόκριση 5xx προκαλεί πάντα επανάληψη;
Όχι. Πολλά συστήματα webhook επαναλαμβάνουν timeouts και σφάλματα διακομιστή, αλλά οι συνθήκες και τα χρονοδιαγράμματα επανάληψης είναι ειδικά για κάθε πάροχο. Αντιμετωπίστε τις επαναλήψεις ως τεκμηριωμένη συμπεριφορά ενσωμάτωσης και επαληθεύστε τις σε περιβάλλον δοκιμών.
Πηγές
- RFC 9110: HTTP Semantics — ορισμοί για επιτυχείς αποκρίσεις, σφάλματα πελάτη, σφάλματα διακομιστή, ανακατευθύνσεις και διαχείριση αποκρίσεων.
- RFC 6585: Additional HTTP Status Codes — προδιαγραφή για το
429 Too Many Requests. - Stripe Webhooks Documentation — πρακτικές οδηγίες για αποκρίσεις webhook, ασύγχρονη επεξεργασία και διαχείριση διπλότυπων συμβάντων.
- GitHub Docs: Handling Webhook Deliveries — έλεγχος παραδόσεων και επιχειρησιακές παράμετροι για ενσωματώσεις webhook.
- 17TRACK Tracking API Documentation — τεκμηρίωση ειδική για τον πάροχο, την οποία πρέπει να ελέγχετε κατά την υλοποίηση ενσωματώσεων Tracking API.


