Webhooks: επαναλήψεις και αναγνωρίσεις

1) Βασικό υπόδειγμα παράδοσης

Τουλάχιστον μία φορά (εξ ορισμού) - Το γεγονός θα παραδοθεί ≥1 φορές. Επακριβώς άπαξ οι εγγυήσεις επιτυγχάνονται με την ιδιοτέλεια του παραλήπτη.
Αναγνώριση (ACK): μόνο κάθε 2xx (συνήθως 200/204) από τον παραλήπτη σημαίνει επιτυχία. Όλα τα άλλα ερμηνεύονται ως αποτυχία και οδηγούν σε επανάληψη.
Γρήγορη ACK: Απαντήστε 2xx μετά την τοποθέτηση του γεγονότος με τη σειρά του, όχι μετά την πλήρη επεξεργασία της επιχείρησης.

2) Μορφότυπος γεγονότων και υποχρεωτικοί τίτλοι

Ωφέλιμο φορτίο (παράδειγμα)

json
{
"id": "evt_01HXYZ",
"type": "order. created",
"occurred_at": "2025-11-03T18:10:12Z",
"sequence": 128374,
"source": "orders",
"data": { "order_id": "o_123", "amount": "49. 90", "currency": "EUR" },
"schema_version": 1
}

Κεφαλίδες αποστολέων

"X-Webhook-Id: evt_01HXYZ' - μοναδικό αναγνωριστικό γεγονότος (χρήση για αφαίρεση).
«X-Webhook-Seq: 128374» - μονοτονική ακολουθία (με συνδρομή/θέμα).
«Χ-Υπογραφή: sha256 = <βάση 64 (hmac_sha256 (σώμα, μυστικό))>» - HMAC - подпись.
'X-Retry: 0,1,2... "είναι ο αριθμός δοκιμής.
«X-Webhook-Version: 1» - έκδοση σύμβασης.
(προαιρετικά) «Traceparent» - συσχέτιση ιχνοστοιχείων.

Απόκριση από τον παραλήπτη

2xx - έγινε δεκτή με επιτυχία (δεν θα υπάρξουν περαιτέρω επαναλήψεις για το 'id').
410 Έφυγε - το τελικό σημείο διαγράφεται/ο ανενεργός αποστολέας → τερματίζει τις επαναλήψεις και απενεργοποιεί την εγγραφή.
429/5xx/timeout - ο αποστολέας επαναλαμβάνεται σύμφωνα με την πολιτική επαναπροώθησης.

3) Πολιτική επιστροφών

Συνιστώμενη εφεδρική κλίμακα (+ jitter)

«1s, 3s, 10s, 30s, 2m, 10m, 30m, 2h, 6h, 24h» (στάση μετά το όριο, για παράδειγμα 48-72 ώρες).

• Εκθετικό εφεδρικό + τυχαίο εκκολαπτήριο (± 20-30%) για την αποφυγή «αγέλης».
• Απαρτία σφαλμάτων για προσωρινές αστοχίες (για παράδειγμα, επανάληψη δοκιμής εάν 5xx ή χρονοδιάγραμμα δικτύου).
• Σεβασμός 429: ορισμός ελάχιστου 'min (Retry-After header, next backoff window)'.

Χρονοδιαγράμματα και μεγέθη

Χρονοδιάγραμμα σύνδεσης ≤ 3-5 δευτερόλεπτα. συνολικός χρόνος απόκρισης ≤ 10 δευτερόλεπτα

Το μέγεθος του οργανισμού βάσει της σύμβασης (π.χ. ≤ 256 KB), διαφορετικά 413 → η λογική «chunking» ή «pull URL».

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

Εφαρμογή idempotent: η επεξεργασία επαναλήψεων του ίδιου 'id' πρέπει να επιστρέφει το ίδιο αποτέλεσμα και να μην αλλάζει κατάσταση ξανά.
Αποθήκευση Dedup στην πλευρά του παραλήπτη: αποθήκευση '(X-Webhook-Id, processed_at, checksum)' με παράθυρα TTL ≥ retray (24-72 ώρες).
Κλείδα σύνθεσης: εάν → διάφορα θέματα «(subscription_id, event_id)».

5) Διαταγή και «επακριβώς εφικτά αποτελέσματα»

• Κατάτμηση ανά κλειδί: το ίδιο λογικό σύνολο (για παράδειγμα, 'order _ id') είναι πάντα σε ένα «κανάλι» της παράδοσης.
• Ακολουθία: Απορρίψτε τα γεγονότα με το παλιό 'X-Webhook-Seq' και βάλτε τα στο «πάρκινγκ» πριν φτάσουν τα αγνοούμενα.

• log των εφαρμοζόμενων πράξεων (outbox/inbox),
• συναλλαγή upsert με 'event _ id' στη βάση δεδομένων,
• sagas/αντισταθμίσεις για πολύπλοκες διαδικασίες.

6) Ανάλυση σφάλματος ανά κωδικό κατάστασης (Πίνακας)

7) Ασφάλεια διαύλων

υπογραφή HMAC κάθε μηνύματος· Ελέγξτε στο δέκτη με το «χρονικό παράθυρο» (mitm and replay attacks).
mTLS για ευαίσθητους τομείς (LCC/πληρωμές).
Επιτρεπόμενος κατάλογος IP των εξερχόμενων διευθύνσεων, TLS 1. 2 +, HSTS.
ελαχιστοποίηση του PII: μην αποστέλλετε περιττά προσωπικά δεδομένα· μεταμφίεση στα κούτσουρα.
Περιστροφή μυστικών: δύο έγκυρα κλειδιά (ενεργά/επόμενα) και η κεφαλίδα 'X-Key-Id' για να υποδείξει την τρέχουσα.

8) Ουρές αναμονής, DLQs και Replays

Τα γεγονότα πρέπει να γράφονται στην ουρά/ημερολόγιο εξόδου στην πλευρά του αποστολέα (για αξιόπιστη αναπαραγωγή).
Αν ξεπεραστεί το μέγιστο των retrays, το γεγονός πηγαίνει στο DLQ (Dead Letter Queue) με την αιτία.
Επανάληψη API (για παραλήπτη/χειριστή): εκ νέου υποβολή με 'id '/εύρος χρόνου/υποκείμενο, με περιορισμό RPS και πρόσθετη υπογραφή/εξουσιοδότηση.

POST /v1/webhooks/replay
{ "subscription_id": "sub_123", "from": "2025-11-03T00:00:00Z", "to": "2025-11-03T12:00:00Z" }
→ 202 Accepted

9) Σύμβαση και έκδοση

Έκδοση του γεγονότος (πεδίο 'schema _ version') και της μεταφοράς ('X-Webhook-Version').
Προσθήκη πεδίων μόνο ως προαιρετικά. σχετικά με τη διαγραφή - ήσσονος σημασίας μετανάστευση και μεταβατική περίοδος (διπλή γραφή).
Τύποι γεγονότων εγγράφων, παραδείγματα, σχήματα (JSON Schemas), κωδικοί σφάλματος.

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

• 'delivery _ success _ rate' (2xx/όλες οι προσπάθειες), 'first _ track _ success _ rate'
• 'retries _ total', 'max _ retry _ age _ seconds', 'dlq _ count'
• 'latency _ p50/p95' (occurred_at → ack_received_at)

• 'ack _ latency' (λήψη 2xx), 'επεξεργασία _ latency' (υποσημείωση)
• 'duplicates _ total', 'invalid _ signature _ total', 'out _ of _ order _ total'

99. Το 9% των συμβάντων λαμβάνουν την πρώτη ACK ≤ 60 δευτερόλεπτα (28d).

• DLQ ≤ 0. 1% του συνόλου· Επανάληψη DLQ ≤ 24 ώρες.

11) Χρονοδιάγραμμα και διαλείμματα δικτύου

Χρήση UTC στα χρονικά πεδία. συγχρονισμός NTP.
Αποστολή 'συνέβη _ στο' και διόρθωση 'παράδοση _ στο' για να διαβάσετε την καθυστέρηση.
Με μεγάλες διακοπές, το δίκτυο/τελικό σημείο → συσσωρεύεται στη σειρά αναμονής, περιορίζοντας την ανάπτυξη (αντίθλιψη + ποσοστώσεις).

12) Συνιστώμενα όρια και υγιεινή

RPS ανά συνδρομή (π.χ. 50 RPS, διάρρηξη 100) + νόμισμα (π.χ. 10).
Το μέγιστο. σώμα: 64-256 KB, για περισσότερες πληροφορίες - «κοινοποίηση + URL» και υπογραφή τηλεφόρτωσης.
Ονόματα γεγονότων στο φίδι. περίπτωση «ή» τελεία. τύπος "('order. δημιουργήθηκε ").
Αυστηρή ταυτότητα των πράξεων εγγραφής του παραλήπτη.

13) Παραδείγματα: Αποστολέας και Παραλήπτης

13. 1 Αποστολέας (ψευδοκώδικας)

python def send_event(event, attempt=0):
body = json. dumps(event)
sig = hmac_sha256_base64(body, secret)
headers = {
"X-Webhook-Id": event["id"],
"X-Webhook-Seq": str(event["sequence"]),
"X-Retry": str(attempt),
"X-Signature": f"sha256={sig}",
"Content-Type": "application/json"
}
res = http. post(endpoint, body, headers, timeout=10)
if 200 <= res. status < 300:
mark_delivered(event["id"])
elif res. status == 410:
deactivate_subscription()
else:
schedule_retry(event, attempt+1) # backoff + jitter, respect 429 Retry-After

13. 2 Δέκτης (ψευδοκώδικας)

python
@app. post("/webhooks")
def handle():
body  = request. data headers = request. headers assert verify_hmac(body, headers["X-Signature"], secret)
evt_id = headers["X-Webhook-Id"]
if dedup_store. exists(evt_id):
return, "" 204 enqueue_for_processing (body) # fast path. dedup_store put(evt_id, ttl=723600)
return, "" 202 # or 204

14) Δοκιμές και πρακτικές χάους

Αρνητικές περιπτώσεις: άκυρη υπογραφή, 429/5xx, timeout, 410, μεγάλα ωφέλιμα φορτία.
Συμπεριφορά: εκτός τάξης, αντίγραφα, καθυστερήσεις 1-10 λεπτών, διάλειμμα για 24 ώρες.
Φορτίο: διάρρηξη 10 ×. Ελέγξτε για αντίθλιψη και εμμονή DLQ.
Συμβάσεις: JSON Schema, υποχρεωτικές επικεφαλίδες, σταθερά είδη γεγονότων.

15) Κατάλογος ελέγχου εφαρμογής

• 2xx = ACK, και γρήγορη επιστροφή μετά την κατάκτηση
• Εκθετική backoff + νευρικότητα, σεβαστείτε 'Retry-After
• Παραλήπτης IDempotency και X-Webhook-Id (TTL ≥ Retray)

Υπογραφές HMAC, μυστική εναλλαγή, προαιρετικό mTLS

• DLQ + Replay API, παρακολούθηση και προειδοποιήσεις
• Όρια: Χρονοδιαγράμματα, RPS, μέγεθος σώματος
• Διάταξη: κατάτμηση ανά κλειδί ή «ακολουθία» + «χώρος στάθμευσης»
• Τεκμηρίωση: σχήματα, παραδείγματα, κωδικοί σφάλματος, εκδόσεις
• Δοκιμές χάους: καθυστερήσεις, αντίγραφα, βλάβη δικτύου, μακρά αναπαραγωγή

16) Mini-FAQ

Πρέπει πάντα να απαντώ σε 200

Κάθε 2xx μετράει ως επιτυχία. 202/204 είναι η συνήθης πρακτική για την «αποδοχή στην ουρά αναμονής».

Μπορούν να σταματήσουν οι επαναλήψεις

Ναι, μια απάντηση 410 ή/και μέσω της κονσόλας/API του αποστολέα (unsubscribe).

Τι γίνεται με τα μεγάλα ωφέλιμα φορτία

Αποστολή «ειδοποίησης + ασφαλούς URL», υπογραφή του αιτήματος λήψης και εγκατάσταση TTL.

Πώς να εξασφαλίσετε την τάξη

Κατάτμηση ανά κλειδί + 'ακολουθία', σε περίπτωση ασυμφωνίας - «χώρος στάθμευσης» και επανάληψη.

Σύνολο

Αξιόπιστα web hooks είναι σαφής σημασιολογία ACK (2xx), λογικές επαναλήψεις με backoff + jitter, αυστηρή idempotence και αφαίρεση, αρμόδια ασφάλεια (HMAC/mTLS), ουρές αναμονής + DLQ + replays, και διαφανής παρατηρησιμότητα. Καθορίστε το συμβόλαιο, εισάγετε όρια και μετρήσεις, εκτελείτε τακτικά σενάρια χάους - και η ενσωμάτωσή σας θα σταματήσει να «χύνεται» στις πρώτες αποτυχίες.