Webhook Επαλήθευση υπογραφής και αδυναμία

Ακολουθεί αυτή η σελίδα Agent Java SDK WEBHOOKS.md κατά τη δέσμευση fa6c7b6. Αυτή είναι μια ενημέρωση μόνο για τεκμηρίωση. Δεν κυκλοφόρησε κανένα νέο SDK τεχνούργημα που να περιέχει βοηθητικές μεθόδους προειδοποίησης.

Και οι τέσσερις τύποι συμβάντων χρησιμοποιούν μια επιστροφή κλήσης εμπόρου URL και αποστέλλονται από το σώμα event. Βλέπω Webhook Προειδοποιήσεις συμβάντων και εκκαθάρισης για πεδία συμβάντων και παραδείγματα ωφέλιμου φορτίου.

Webhook κεφαλίδες

timestamp + nonce + rawBody

Αδυναμία γεγονότος

Συνεχίστε την κατάργηση διπλότυπων εντός του εμπόρου και του πεδίου environment, ατομικά με επιχειρηματική επεξεργασία. Διαφορετικές τιμές notificationId προσδιορίζουν ανεξάρτητες FIRST / UPGRADE / REMINDER ειδοποιήσεις. μην απορρίπτετε τις ειδοποιήσεις ομαδοποιώντας τον χρήστη, το επεισόδιο ή το eventType. Ένα κενό κλειδί αδυναμίας δεν μπορεί να χρησιμοποιηθεί για την αφαίρεση διπλότυπων. Το SDK επιστρέφει μόνο ένα βοηθητικό κλειδί. δεν διατηρεί ούτε επεξεργάζεται επιχειρηματικά δεδομένα. Καταγράψτε την ίδια ταυτότητα με διαφορετικό σώμα ως σύγκρουση. μην αντικαθιστάτε το επεξεργασμένο σώμα.

Επαλήθευση και παραλαβή υπογραφής

Χρησιμοποιήστε το εμπορικό μυστικό API για να υπολογίσετε την HMAC-SHA256 δεκαεξαδική υπογραφή του timestamp + nonce + rawBody. Επαληθεύστε τα αρχικά ληφθέντα byte. Μην μορφοποιήσετε το JSON, μην μετονομάσετε πεδία και μην επανασειριοποιήσετε πρώτα το σώμα.

Επαληθεύστε πρώτα την υπογραφή και, στη συνέχεια, ελέγξτε το χρονικό παράθυρο (συνιστάται ±300 δευτερόλεπτα), τον έμπορο και το περιβάλλον. Στη συνέχεια, εξαγάγετε την ταυτότητα αδυναμίας και χειριστείτε την ειδοποίηση αξιόπιστα. Διατήρηση άγνωστων τιμών συμβάντων για διάγνωση. Ποτέ μην τα ερμηνεύσετε ως επιτυχία κεφαλαίων. Ο βοηθός επαλήθευσης δεν εκτελεί ελέγχους χρονικού παραθύρου, ιδιοκτησίας ή μόνιμης κατάργησης διπλότυπων.

Επιστρέψτε HTTP 2xx μετά την ολοκλήρωση της επεξεργασίας ή την επιβεβαίωση ενός πανομοιότυπου διπλότυπου. επιστροφή μη 2xx σε περίπτωση αποτυχίας. Ο αποστολέας προειδοποίησης έχει χρονικό όριο 5 δευτερολέπτων HTTP και το πολύ 8 προσπάθειες. Οι επαναλήψεις διατηρούν το παγωμένο σώμα. μόνο η χρονική σφραγίδα της υπογραφής και καμία αλλαγή. Απαντήστε αμέσως μετά από αξιόπιστη αποδοχή. Η μακροχρόνια επιχειρηματική εργασία μπορεί να χρησιμοποιήσει τις επίμονες εργασίες του ίδιου του εμπόρου.

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

Επιτυχείς απαντήσεις και διακοπή επαναλήψεων

Οι επιστροφές χρημάτων και οι προειδοποιήσεις εκκαθάρισης χρησιμοποιούν μόνο το HTTP κωδικός κατάστασης για να προσδιορίσετε την επιτυχία παράδοσης. Ο αποστολέας δεν ερμηνεύει την απάντηση-σώμα code, success, result, ή message, και δεν απαιτεί επιδιόρθωση OK / success απάντηση.

Το σώμα απόκρισης μπορεί να είναι κενό, κείμενο ή JSON. Τα πεδία του παραδείγματος result είναι ενημερωτικά για τον έμπορο και όχι απαιτήσεις πρωτοκόλλου. Το 202 Accepted διακόπτει επίσης τις επαναλήψεις της πλατφόρμας, επομένως επιστρέψτε την μόνο αφού αποθηκεύσετε αξιόπιστα την ειδοποίηση στη μόνιμη ουρά εργασιών του εμπόρου, όχι απλώς ξεκινώντας μια εργασία ασύγχρονου στη μνήμη.

Παραδείγματα επιτυχημένων απαντήσεων

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

HTTP/1.1 200 OK
Content-Type: application/json
{"result":"RECEIVED"}

Όταν δεν απαιτείται φορέας απάντησης:

HTTP/1.1 204 No Content

Για μια ήδη επεξεργασμένη ειδοποίηση με πανομοιότυπο σώμα, παραλείψτε τη διπλότυπη επαγγελματική επεξεργασία και συνεχίστε να επιστρέψετε 2xx:

HTTP/1.1 200 OK
Content-Type: application/json
{"result":"DUPLICATE"}

Παραδείγματα απόκρισης αποτυχίας

Εάν η βάση δεδομένων δεν είναι προσωρινά διαθέσιμη και ο έμπορος δεν έχει ολοκληρώσει την επεξεργασία ούτε έχει αποθηκεύσει αξιόπιστα την ειδοποίηση, επιστρέψτε το non-2xx, ώστε η πλατφόρμα να προσπαθήσει ξανά:

HTTP/1.1 503 Service Unavailable
Content-Type: application/json
{"result":"FAILED","message":"temporary storage failure"}

Απόρριψη μη έγκυρης υπογραφής χωρίς ενημέρωση επιχειρηματικών δεδομένων ή επιτυχείς εγγραφές κατάργησης διπλότυπων:

HTTP/1.1 401 Unauthorized
Content-Type: application/json
{"result":"INVALID_SIGNATURE"}

Αυτά τα όργανα απάντησης δεν αλλάζουν τις αποφάσεις επανάληψης. Μην περιμένετε ένα 401 ή 409 να σταματήσει οριστικά τις επαναλήψεις. διερευνήστε την υπογραφή, το περιεχόμενο ειδοποίησης ή τη διαμόρφωση του εμπόρου.

Λανθασμένο παράδειγμα: η ακόλουθη απάντηση εξακολουθεί να λογίζεται ως επιτυχής παράδοση. Η πλατφόρμα δεν θα προσπαθήσει ξανά λόγω success:false.

HTTP/1.1 200 OK
Content-Type: application/json
{"success":false,"code":500,"message":"processing failed"}

Εάν ο χειριστής πλαισίου ή καθολικής εξαίρεσης αναδιπλώνει τις επιχειρηματικές αποτυχίες σε HTTP 200, ορίστε ρητά τη σωστή κατάσταση αποτυχίας στο τελικό σημείο επανάκλησης.

Αξιόπιστη επιβεβαίωση και διπλή παράδοση

Συνιστώμενη παραγγελία: επαληθεύστε την υπογραφή και ελέγξτε τον χρόνο / έμπορο / περιβάλλον → εξάγετε την ταυτότητα αδυναμίας → επεξεργαστείτε επιχειρηματικά δεδομένα και επιτυχείς εγγραφές κατάργησης διπλότυπων σε μια συναλλαγή ή αποθηκεύστε αξιόπιστα μια εκκρεμή εργασία → επιστροφή 200/204 μετά την επιτυχία της δέσμευσης. Μην επιστρέψετε 2xx και μην επισημάνετε την ειδοποίηση που υποβλήθηκε σε επεξεργασία πριν από την επιτυχή εγγραφή της βάσης δεδομένων.

Η διπλότυπη παράδοση μπορεί να εξακολουθήσει να συμβαίνει μετά την επιτυχία της επεξεργασίας από τον έμπορο: η απόκριση μπορεί να χαθεί ή η πλατφόρμα μπορεί να λάβει 2xx αλλά να μην επιμένει SUCCESS. Οι επιστροφές κλήσης HTTP δεν εγγυώνται την εφάπαξ παράδοση. Συνεχίστε την κατάργηση διπλότυπων εντός του εμπόρου και του πεδίου environment. Τα κεφάλαια χρησιμοποιούν orderType:orderId:targetStatus; προειδοποιήσεις χρησιμοποιήστε liquidation.warning:notificationId. Για ένα πανομοιότυπο φορέα που έχει ήδη υποστεί επεξεργασία, επιστρέψτε 2xx χωρίς πίστωση χρημάτων ή έκδοση υπενθύμισης ξανά. Για την ίδια ταυτότητα με διαφορετικό σώμα, καταγράψτε μια διένεξη και επιστρέψτε non-2xx. μην αντικαταστήσετε την αρχική εγγραφή.

Επιτυχία επιβεβαίωσης σημαίνει ότι ο έμπορος έλαβε / επεξεργάστηκε την ειδοποίηση και όχι ότι η λειτουργία κεφαλαίων πέτυχε. Αφού καταγράψετε μια έγκυρη ειδοποίηση χρημάτων με targetStatus=FAILED, επιστρέψτε επίσης 2xx. μια αποτυχία παραγγελίας δεν αποτελεί λόγο απόρριψης της επιβεβαίωσης ειδοποίησης.

Χρηματοδότηση και περιβαλλοντικά όρια

Η αρχική μεταφορά συμβολαίου webhook και η ροή queryOrder δεν ισχύουν αυτόματα για τη χρηματοδότηση. Επιβεβαιώστε τις λειτουργίες χρηματοδότησης χρησιμοποιώντας το queryWalletTransfer και το αρχικό περιβάλλον παραγγελίας. Χρήσεις χρηματοδότησης status; Οι αρχικές απαντήσεις μεταφοράς συμβολαίου χρησιμοποιήστε orderStatus. Μια επιτυχημένη απάντηση HTTP ή code=0 δεν αποδεικνύει από μόνη της ότι μετακινήθηκαν χρήματα.

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

Οδηγός ανάκτησης χρηματοδότησης · Οδηγός περιβάλλοντος