Webhook Επαλήθευση υπογραφής & Idempotency

Webhooks ειδοποιήσετε ένα backend συνεργάτη για ασύγχρονες αλλαγές επιχειρηματικής κατάστασης. Επειδή η παράδοση μπορεί να επαναληφθεί, κάθε παραλήπτης πρέπει να επαληθεύσει την υπογραφή πριν από την ανάλυση αξιόπιστων δεδομένων και πρέπει να επεξεργαστεί το συμβάν ανίκανα.

Webhook κεφαλίδες

Κεφαλίδα	Περιγραφή
X-Agent-Χρονική σήμανση	Χρονική σήμανση Unix σε δευτερόλεπτα.
X-Agent-Nonce	Προστασία επανάληψης nonce.
X-Agent-Υπογραφή	HMAC-SHA256 υπογραφή.

timestamp + nonce + rawBody

Χρησιμοποιήστε το ακριβές σώμα του μη επεξεργασμένου αιτήματος που λάβατε πάνω από HTTP κατά την ανακατασκευή της υπογεγραμμένης τιμής. Η ανάλυση και η εκ νέου σειριοποίηση JSON πρώτα μπορεί να αλλάξει το κενό διάστημα ή τη σειρά των πεδίων και να παράγει μια διαφορετική υπογραφή.

Ροή επαλήθευσης

Διαβάστε τις κεφαλίδες χρονικής σήμανσης, nonce και υπογραφής.
Καταγράψτε το μη τροποποιημένο ακατέργαστο σώμα αιτήματος.
Κατασκευάστε timestamp + nonce + rawBody.
Υπολογίστε HMAC-SHA256 με τον σύντροφο API μυστικό.
Συγκρίνετε τις υπογραφές που υπολογίστηκαν και ελήφθησαν χρησιμοποιώντας μια σύγκριση σταθερού χρόνου.
Εφαρμόστε τους εγκεκριμένους ελέγχους χρονικής σήμανσης-φρεσκάδας και μη επαναχρησιμοποίησης.
Αναλύστε και επεξεργαστείτε το συμβάν μόνο μετά την επιτυχία της επαλήθευσης.

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

Παραγγελία idempotency

Υπόθεση	Χειρισμός
Αρχικό αίτημα μεταφοράς	Δημιουργήστε ένα παγκοσμίως μοναδικό agentOrderNo.
HTTP τάιμ άουτ	Ρωτήστε το αρχικό agentOrderNo πριν δημιουργήσετε ένα νέο.
PROCESSING απάντηση	Περιμένετε webhook ή υποβάλετε ερώτημα για την κατάσταση της παραγγελίας.
Επαναλαμβανόμενες webhook	Διαγραφή διπλότυπων με βάση το κλειδί idempotency και την τελική κατάσταση.

Συνιστώμενο αρχείο ανικανότητας

Αποθηκεύστε αρκετές πληροφορίες για να αναγνωρίσετε μια επαναλαμβανόμενη παράδοση και να ανακτήσετε με ασφάλεια:

Πεδίο	Σκοπός
Κλειδί συμβάντος ή επιχείρησης	Προσδιορίζει μοναδικά την ειδοποίηση ή τη λειτουργία.
Αριθμός παραγγελίας συνεργάτη	Συνδέει το συμβάν με το αρχικό αίτημα.
Κατακερματισμός ωφέλιμου φορτίου	Βοηθά στον εντοπισμό επαναλαμβανόμενων ωφέλιμων φορτίων σε διένεξη.
Τρέχουσα κατάσταση επεξεργασίας	Διακρίνει τη ληφθείσα, την επεξεργασία, την επιτυχία και την αποτυχημένη εργασία.
Τελική κατάσταση επιχείρησης	Αποτρέπει την εφαρμογή μιας ενέργειας τερματικού δύο φορές.
Επεξεργασμένη χρονική σήμανση	Υποστηρίζει πολιτικές έρευνας και διατήρησης.

Καταχωρίστε το αρχείο επιχειρηματικής αλλαγής και ανικανότητας στην ίδια συναλλαγή, όπου είναι δυνατόν. Ένα επαναλαμβανόμενο συμβάν θα πρέπει να επιστρέψει το ήδη γνωστό αποτέλεσμα αντί να εφαρμόσει ξανά το υπόλοιπο, την παραγγελία ή την αλλαγή χρήστη.

Κανόνας χρονικού ορίου και επανάληψης

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

Λίστα ελέγχου παραγωγής

Επαληθεύστε την υπογραφή πριν από JSON ανάλυση ή την επιχειρηματική επεξεργασία.
Διατηρήστε το ακατέργαστο σώμα ανεξάρτητα από το αναλυμένο ωφέλιμο φορτίο.
Απορρίψτε τα αιτήματα που δεν είναι ενημερωμένα ή έχουν επαναληφθεί σύμφωνα με την εγκεκριμένη πολιτική ενσωμάτωσης.
Κάντε την επεξεργασία συμβάντων ασφαλή για επαναλαμβανόμενη παράδοση και παράδοση εκτός παραγγελίας.
Καταγράψτε αναγνωριστικά συμβάντων, αριθμούς παραγγελιών συνεργατών, αποτέλεσμα επεξεργασίας και χρόνο αιτήματος.
Αποκρύψτε μυστικά και τιμές υπογραφής από αρχεία καταγραφής και συνημμένα υποστήριξης.

Μυστικά & HMAC Υπογραφή

Προστατέψτε το μυστικό API που χρησιμοποιείται για την επαλήθευση αιτήματος και webhook .

Agent SDK Επισκόπηση

Ελέγξτε την πλήρη ροή εργασιών ενοποίησης παρασκηνίου.

SDK Αντιμετώπιση προβλημάτων