Εγγυήσεις παράδοσης Webhook

Τα Webhooks είναι ασύγχρονες ειδοποιήσεις συστήματος προς συνδρομητή μέσω HTTP (S). Το δίκτυο είναι αναξιόπιστο: οι απαντήσεις χάνονται, τα πακέτα έρχονται σε αντίγραφα ή εκτός λειτουργίας. Ως εκ τούτου, οι εγγυήσεις παράδοσης δεν είναι κατασκευασμένες «πάνω από TCP», αλλά στο επίπεδο του πρωτοκόλλου webhook και domain idempotency.

Ο βασικός στόχος: παροχή τουλάχιστον άπαξ παράδοσης με παραγγελία ανά κλειδί (όπου είναι απαραίτητο), παροχή υλικών συνδρομητών για την ευφυή επεξεργασία και ενός εργαλείου συμφιλίωσης για την αποκατάσταση.

1) Επίπεδα εγγύησης

Βέλτιστη προσπάθεια - μια εφάπαξ προσπάθεια, χωρίς ρετρά. Αποδεκτό μόνο για «ασήμαντα» γεγονότα.
Τουλάχιστον μία φορά (συνιστώμενη) - είναι δυνατά τα αντίγραφα και τα αντίγραφα εκτός παραγγελίας, αλλά το γεγονός παραδίδεται υπό τον όρο ότι ο συνδρομητής είναι διαθέσιμος εντός ευλόγου χρονικού διαστήματος.
Αποτελεσματικά ακριβώς μία φορά (στο επίπεδο επίδρασης) - που επιτυγχάνεται με συνδυασμό της ιδιαιτερότητας και της αποθήκευσης dedup στην πλευρά του συνδρομητή/αποστολέα. «Ακριβώς μία φορά» οι μεταφορές HTTP δεν είναι δυνατές.

2) Σύμβαση webhook: ελάχιστη απαιτούμενη

X-Webhook-Id: 5d1e6a1b-4f7d-4a3d-8b3a-6c2b2f0f3f21  # глобальный ID события
X-Delivery-Attempt: 3                 # номер попытки
X-Event-Type: payment.authorized.v1          # тип/версия
X-Event-Time: 2025-10-31T12:34:56Z          # ISO8601
X-Partition-Key: psp_tx_987654            # ключ порядка
X-Seq: 418                      # монотонный номер по ключу
X-Signature-Alg: HMAC-SHA256
X-Signature: t=1730378096,v1=hex(hmac(secret, t        body))
Content-Type: application/json

json
{
"id": "5d1e6a1b-4f7d-4a3d-8b3a-6c2b2f0f3f21",
"type": "payment.authorized.v1",
"occurred_at": "2025-10-31T12:34:56Z",
"partition_key": "psp_tx_987654",
"sequence": 418,
"data": {
"payment_id": "psp_tx_987654",
"amount": "10.00",
"currency": "EUR",
"status": "AUTHORIZED"
},
"schema_version": 1
}

Η απαίτηση για τον παραλήπτη: να αντιδρά γρήγορα '2xx' μετά την προσθήκη και την επικύρωση της υπογραφής, και να επεξεργάζεται ασύγχρονα τις επιχειρήσεις.

3) Τάξη και αιτιώδης συνάφεια

Βασική σειρά: η εγγύηση «δεν θα φύγει» μόνο στο εσωτερικό μιας «κατάτμησης _ κλειδιού» (π.χ. 'player _ i ,' πορτοφόλι _ i , 'psp _ tx _ id').
Η παγκόσμια τάξη δεν είναι εγγυημένη.
Από την πλευρά του αποστολέα υπάρχει μια ουρά με σειρά από το κλειδί (ένας καταναλωτής/sharding), από την πλευρά του παραλήπτη υπάρχει ένα εισερχόμενο με '(πηγή, event_id)' και προαιρετικά περιμένει για λείπει 'seq'.

Εάν τα κενά είναι κρίσιμα - να παρασχεθεί pull-API 'GET/events μετά = σημείο ελέγχου «για την κάλυψη της υστέρησης και τη διαβούλευση».

4) Ιδιαιτερότητα και αποπροσανατολισμός

Κάθε webhook φέρει ένα σταθερό «X-Webhook-Id».
Ο παραλήπτης αποθηκεύει "εισερχόμενα (event_id)": PK - "πηγή + event_id'. επαναλαμβάνει → μη-op.
Οι ανεπιθύμητες ενέργειες (γραφή στη βάση δεδομένων/πορτοφόλι) πραγματοποιούνται μόνο μία φορά όταν το συμβάν εμφανίζεται για πρώτη φορά.
Για εντολές με ισχύ, χρησιμοποιήστε το Idempotency-Key και την κρύπτη αποτελεσμάτων για τη διάρκεια του παραθύρου retray.

5) Retrai, backoff και παράθυρα

• Επανεκπαίδευση σε '5xx/timeout/ error/409-Conflict σύνδεσης (retryable )/429'.
• Μην ανασυρθείτε στο '4xx' εκτός από '409/423/429' (και μόνο με συνεπή σημασιολογία).
• Εκθετική εφεδρεία + πλήρης νευρικότητα: 0. 5s, 1s, 2s, 4s, 8s,... έως 'max = 10-15 λεπτά', Παράθυρα επανακυκλοφορίας TTL: για παράδειγμα, 72 ώρες.
• Σεβασμός «Retry-After» από τον παραλήπτη.
• Έχετε μια κοινή προθεσμία: «Αναγνωρίστε το γεγονός ως μη παραδοθέν» και μεταφέρετε το στην DLQ.

yaml retry:
initial_ms: 500 multiplier: 2.0 jitter: full max_delay_ms: 900000 ttl: 72h retry_on: [TIMEOUT, 5xx, 429]

6) DLQ и redrive

DLQ - «νεκροταφείο» δηλητηριωδών ή TTL γεγονότων που έχουν λήξει με πλήρη μετα-πληροφορίες (ωφέλιμο φορτίο, κεφαλίδες, σφάλματα, απόπειρες, hashes).
Κονσόλα ιστού/API για redrive (point re-delivery) με προαιρετικό τελικό σημείο/μυστική επεξεργασία.
Τόκοι-περιορισμένοι redrive και παρτίδες-redrive προτεραιότητα.

7) Ασφάλεια

mTLS (εάν είναι δυνατόν) ή TLS 1. 2+.

1. Εξάγεται " (χρονοσφραγίδα) από την κεφαλίδα, ελέγχεται το συρόμενο παράθυρο (π.χ. ± 5 λεπτά).

8) Ποσοστώσεις, όρια επιτοκίων και ίδια κεφάλαια

Δίκαιη αναμονή ανά ενοικιαστή/συνδρομητή: έτσι ώστε ένας συνδρομητής/μισθωτής να μην επιτυγχάνει τη συνολική συγκέντρωση.
Ποσοστώσεις και όρια διάρρηξης για την εξερχόμενη κυκλοφορία και ανά τελικό σημείο.
Αντίδραση στο '429': τιμή 'Retry-After', ροή τρολ. για μακροπρόθεσμο περιορισμό - υποβάθμιση (αποστολή μόνο κρίσιμων τύπων γεγονότων).

9) Κύκλος ζωής συνδρομής

Μητρώο/Επαλήθευση: POST τελικό σημείο → πρόκληση/απόκριση ή επιβεβαίωση εκτός ζώνης.
Μίσθωση (προαιρετικά): η υπογραφή ισχύει μέχρι την ημερομηνία «ισχύον _ to». παράταση - ρητή.
Μυστική περιστροφή: 'current _ secre ,' next _ secre 'switch _ at'.
Δοκιμή ping: τεχνητό γεγονός για τη δοκιμή της διαδρομής πριν από την ενεργοποίηση των κύριων θεμάτων.
Δείγματα υγείας: περιοδικός έλεγχος HEAD/GET με καθυστέρηση και έλεγχο προφίλ TLS.

10) Εξέλιξη των συστημάτων (εκδόσεις γεγονότων)

Τύπος γεγονότος έκδοσης: 'πληρωμή. έχει εγκριθεί. v1 '→'... v2 '.
Εξέλιξη - πρόσθετο (νέα πεδία → εκδόσεις MINOR API), θραύση → νέο τύπο.
Μητρώο Schema (JSON-Schema/Avro/Protobuf) + αυτόματη επικύρωση πριν από την υποβολή.
Η κεφαλίδα 'X-Event-Type' και το πεδίο 'schema _ version' στο σώμα είναι και τα δύο απαραίτητα.

11) Παρατηρησιμότητα και SLO

• 'deliveries _ total', '2xx/4xx/5xx _ rate', 'timeout _ rate', 'signature _ fail _ rate'.
• 'attempts _ avg', 'p50/p95/p99 _ delivery _ latency _ m (δημοσίευση στο 2xx).
• 'dedup _ rate', 'out _ of _ order _ rate', 'dlq _ rate', 'redrive _ success _ rate'.
• 'queue _ depth', 'oldest _ in _ queue _ m ,' thottle _ event .

• Το μερίδιο των παραδόσεων ≤ 60 s (p95) - 99. 5% για κρίσιμα συμβάντα.
• DLQ ≤ 0. 1% σε 24 ώρες
• Αποτυχία υπογραφής ≤ 0. 05%.

: 'event _ i ,' spartion _ key ',' seq ',' track ',' endpoint ',' tenant _ i , 'schema _ version', 'trace _ i .

12) Αλγόριθμος αναφοράς αποστολέα

1. Εγγραφή γεγονότος στο outbox συναλλαγών.
2. Ορίστε partition_key και επόμενες. ουρά αναμονής.
3. Ο εργαζόμενος λαμβάνει ανά κλείδα, έντυπα αιτήματος, πινακίδες, αποστέλλει με χρονοδιαγράμματα (σύνδεση/ανάγνωση).
4. Με το '2xx' - να αναγνωριστεί ως παραδοθέν, να οριστεί η καθυστέρηση και το σημείο ελέγχου seq.
5. Με '429/5xx/timeout' - υποχώρηση σύμφωνα με την πολιτική.
6. Με TTL → DLQ και συναγερμός.

13) Επεξεργαστής αναφοράς (δέκτης)

1. Δέχεται την αίτηση, ελέγχει το TLS/proto.
2. Επικύρωση υπογραφής και χρονοθυρίδας.
3. Γρήγορη ACK 2xx (μετά από συγχρονισμένη εγγραφή στα τοπικά εισερχόμενα/ουρά αναμονής).
4. Ο ασύγχρονος εργαζόμενος διαβάζει 'εισερχόμενα', ελέγχει 'event _ id' (παππούς), αν είναι απαραίτητο, παραγγελίες από 'seq' inside 'κατάτμηση _ κλειδί'.
5. Εκτελεί εφέ, γράφει «σημείο ελέγχου όφσετ/seq» για συμφιλίωση.
6. Σε περίπτωση σφάλματος - τοπικά retrays· «δηλητηριώδη» καθήκοντα → τοπικό DLQ με προειδοποιήσεις.

14) Συμφιλίωση (βρόχος συγκέντρωσης)

• 'GET/events? partition_key=...&after_seq=...&limit=...' - να δώσει όλα τα χαμένα.
• Σημείο ελέγχου Token: 'μετά = αδιαφανές _ token' αντί για seq.
• Idempotent redelivery: το ίδιο 'event _ id', η ίδια υπογραφή στο νέο 't'.

15) Χρήσιμες επικεφαλίδες και κωδικοί

2xx - αποδεκτή (ακόμη και αν η επεξεργασία επιχειρήσεων είναι μεταγενέστερη).
410 Έφυγε - το τελικό σημείο είναι κλειστό (ο αποστολέας σταματά την παράδοση και σηματοδοτεί την εγγραφή ως «αρχειοθετημένη»).
409/423 - ο προσωρινός αποκλεισμός του retray των πόρων είναι λογικός.
429 - πολύ συχνά → γκάζι και εφεδρεία.
σφάλμα διαμόρφωσης· Σταματήστε το ρετράι, ανοίξτε το εισιτήριο.

16) Πολυπληθείς και περιφέρειες

Ατομικές ουρές και όρια ανά ενοικιαστή/τελικό σημείο.
Κατοικία δεδομένων: αποστολή δεδομένων από την περιοχή. κεφαλίδες «X-Tenant», «X-Region».
απομόνωση αστοχιών: η πτώση ενός συνδρομητή δεν επηρεάζει τους υπόλοιπους (χωριστές ομάδες).

17) Δοκιμές

Δοκιμές συμβάσεων: σταθερά παραδείγματα φορέων/υπογραφών, έλεγχος επικύρωσης.
Χάος: σταγόνα/αντίγραφα, ανακατωσούρα, καθυστερήσεις δικτύου, σφάλματα 'RST', 'TLS'.
Φορτίο: καταιγίδα διάρρηξης, μετρούμενη σε p95/p99.
Ασφάλεια: αντι-αναπαραγωγή, παρωχημένη χρονοσφραγίδα, λάθος μυστικά, περιστροφή.
DR/Replay: Μάζα redrive από DLQ σε μεμονωμένο περίπτερο.

18) Playbooks (runbooks)

1. Ανάπτυξη 'υπογραφή _ αποτυχία _ ποσοστό'

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

2. Η σειρά αναμονής είναι παλαιότερη ('παλαιότερη _ in _ queue _ m ↑)

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

3. Καταιγίδα '429' σε συνδρομητή

Ενεργοποίηση στραγγαλισμού και παύσεων μεταξύ των προσπαθειών. μετατόπιση λιγότερο κρίσιμων τύπων γεγονότων.

4. Μάζα '5xx"

Διακόπτης ανοικτού κυκλώματος για συγκεκριμένο τελικό σημείο, μετάβαση σε αναβολή & παρτίδα. σήμα προς τον συνδρομητή.

5. Συμπλήρωση DLQ

Σταματήστε τις μη κρίσιμες εκδόσεις, ενεργοποιήστε το redrive παρτίδων με χαμηλή RPS, συγκεντρώστε ειδοποιήσεις στους ιδιοκτήτες συνδρομής.

19) Τυπικά σφάλματα

Συγχρονισμένη βαριά επεξεργασία σε 2xx απόκριση → ρετιρέ και αντίγραφα.
Καμία υπογραφή αμαξώματος/χρονικού παραθύρου → ευπάθεια υποκατάστασης/αναπαραγωγής.
Η απουσία 'event _ id' και 'inbox' → δεν μπορεί να γίνει idempotent.
Μια απόπειρα «παγκόσμιας τάξης» → αιώνιες κλειδαριές αναμονής.
Υποχωρήσεις χωρίς νευρικότητα/όρια → εντατικοποίηση συμβάντων (βροντή αγέλη).
Μια κοινή κοινοπραξία για όλους τους συνδρομητές → «θορυβώδης» θέτει τους πάντες.

20) Κατάλογος επιλογών πριν από την πώληση

• Σύμβαση: 'event _ id', 'spartion _ key', 'seq', 'event _ type. vN ', υπογραφή HMAC και χρονοσφραγίδα.
• Αποστολέας: outbox, serialization by key, retrays with backoff + jitter, TTL, DLQ and redrive.
• Παραλήπτης: γρήγορη εγγραφή στα εισερχόμενα + 2xx; αγωγή idempotent· τοπική DLQ.
• Ασφάλεια: TLS, υπογραφές, αντι-αναπαραγωγή, διπλή μυστικότητα, εναλλαγή.
• Ποσοστώσεις/όρια: δίκαιη ουρά ανά ενοικιαστή/τελικό σημείο, τήρηση «Retry-After».
• Συμφιλίωση API και σημείων ελέγχου. τεκμηρίωση για τους συνδρομητές.
• Παρατηρησιμότητα: p95/threads/errors/DLQ, ίχνος σε 'event _ id'.
• Εκδοχή γεγονότων και πολιτική εξέλιξης σχημάτων.
• Βιβλία παιχνιδιών περιστατικών και παγκόσμιο κουμπί παύσης/αποπάγωσης.

Συμπέρασμα

Τα έμπιστα webhooks είναι ένα πρωτόκολλο στην κορυφή του HTTP, όχι μόνο "POST με JSON. "Ένα σαφές συμβόλαιο (ID, κλειδί παραγγελίας, υπογραφή), idempotency, retray με νευρικότητα, δίκαιη ουρά αναμονής και καλά αποσφαλματωμένα playbooks μετατρέπουν την καλύτερη περίπτωση σε ένα προβλέψιμο και μετρήσιμο μηχανισμό παράδοσης. Κατασκευάστε τουλάχιστον μία φορά + τάξη κλειδιών + συμφιλίωση, και το σύστημα θα επιβιώσει ήρεμα στο δίκτυο, τις κορυφές φορτίου και τα ανθρώπινα σφάλματα.