Webhooks and event idempotency

TL· DR

Ένα καλό webhook είναι ένα υπογεγραμμένο (HMAC/mTLS), συνοπτικό και idempotent event που παραδίδεται σε ένα μοντέλο τουλάχιστον μία φορά με εκθετική backoff και αφαίρεση στον παραλήπτη. Συμφωνήστε σε ένα φάκελο ('event _ i ,' type ',' ts ',' version ',' track ',' signature '), χρονικό παράθυρο ( λεπτά), κωδικούς απόκρισης, retrays, DLQ και τελικό σημείο κατάστασης.

1) Ρόλοι και μοντέλο υλοποίησης

Αποστολέας (εσείς/πάροχος): δημιουργεί ένα γεγονός, πινακίδες, προσπαθεί να παραδώσει μέχρι 2xx, επαναδιατυπώνει στο 3xx/4xx/5xx (εκτός από το ρητό «μην αποδεχθείτε»), οδηγεί DLQ, δίνει επανάληψη API.
Παραλήπτης (εταίρος/υπηρεσία σας): ελέγχει την υπογραφή/χρονικό παράθυρο, κάνει dedup και idempotent επεξεργασία, απαντά με τον σωστό κωδικό, παρέχει/status και/ack replay από 'event _ id'.

Εγγυήσεις: τουλάχιστον μία φορά. Ο παραλήπτης πρέπει να μπορεί να χειρίζεται αντίγραφα και να επαναταξινομεί.

2) Φάκελος της εκδήλωσης

json
{
"event_id": "01HF7H9J9Q3E7DYT5Y6K3ZFD6M",
"type": "payout.processed",
"version": "2025-01-01",
"ts": "2025-11-03T12:34:56.789Z",
"attempt": 1,
"producer": "payments",
"tenant": "acme",
"data": {
"payout_id": "p_123",
"status": "processed",
"amount_minor": 10000,
"currency": "EUR"
}
}

Τα απαιτούμενα πεδία είναι "event _ i ," type "," version "," ts "," track ".
Κανόνες εξέλιξης: προσθήκη πεδίων. διαγράψτε/αλλάξτε τύπους - μόνο με τη νέα «έκδοση».

3) Ασφάλεια: υπογραφές και δεσμευτικές

3. Υπογραφή 1 HMAC (συνιστάται εξ ορισμού)

X-Signature: v1=base64(hmac_sha256(<secret>, <canonical>))
X-Timestamp: 2025-11-03T12:34:56Z
X-Event-Id: 01HF7...

<timestamp>\n<method>\n<path>\n<sha256(body)>

• abs (τώρα − 'X-Timestamp') ≤ 300s
• "X-Event-I not που έχει υποστεί επεξεργασία πριν (dedup)
• 'X-Υπογραφή' matches (χρονικά ασφαλής σύγκριση)

3. 2 Πρόσθετα μέτρα

mTLS για εξαιρετικά ευαίσθητους δικτυακούς τόπους.
Κατάλογος αδειών IP/ASN.
DPoP (προαιρετικό) για αποστολέα που περιορίζεται εάν το webhook ενεργοποιεί callbacks.

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

4. 1 Ιδιαιτερότητα γεγονότος

• αποθήκευση "event _ i in the idempotent cache (KV/Redis/DB) on TTL 24-72 ώρες·
• εξοικονομεί το αποτέλεσμα της επεξεργασίας (επιτυχία/σφάλμα, τεχνουργήματα) για επιστροφή.

4. 2 Εντολή idempotency (callbacks)

Αν το webhook αναγκάσει τον πελάτη να τραβήξει το API (για παράδειγμα, «επιβεβαίωση πληρωμής»), χρησιμοποιήστε το 'Idempotency-Key' στην κλήση REST, αποθηκεύστε το αποτέλεσμα στην πλευρά της υπηρεσίας (ακριβώς μία φορά το αποτέλεσμα).

key: idempotency:event:01HF7...
val: { status: "ok", processed_at: "...", handler_version: "..." }
TTL: 3d

5) Retrai και backoff

• «5s, 15s, 30s, 30s, 1m, 2m, 5m, 10m, 30m, 1h, 3h, 6h, 12h, 24h» (τότε καθημερινά μέχρι τις ημέρες Ν)

• 2xx - επιτυχία, stop retrays.

• '400/ 401/403/404/422' - δεν μπορεί να επαναδιατυπωθεί εάν η υπογραφή/ο μορφότυπος είναι εντάξει (σφάλμα πελάτη).
• '429' - retrayim by 'Retry-After' or backoff.
• 5xx/δίκτυο - retrayim.

Κεφαλίδες αποστολέων: 'User-Agent', 'X-Webhook-Production', 'X-Trust'.

6) Πλευρική επεξεργασία του παραλήπτη

pseudo verify_signature()
if abs(now - X-Timestamp) > 300s: return 401

if seen(event_id):
return 200 // идемпотентный ответ

begin transaction if seen(event_id): commit; return 200 handle(data)       // доменная логика mark_seen(event_id)    // запись в KV/DB commit return 200

Συναλλαγή: Η ετικέτα «ορατή» πρέπει να τοποθετείται ατομικά με αποτέλεσμα την πράξη (ή μετά τον καθορισμό του αποτελέσματος) ώστε να αποφεύγεται η διπλή επεξεργασία σε περίπτωση βλάβης.

7) Εγγυήσεις τάξης και στιγμιότυπα

Η τάξη δεν είναι εγγυημένη. Χρήση 'ts' και domain 'seq '/' version' στα 'δεδομένα' για την επαλήθευση της συνάφειας.
Για μεγάλες καθυστερήσεις/απώλειες - προσθήκη/επανάληψη στον αποστολέα και/resync στον παραλήπτη (λήψη στιγμιότυπου και δέλτα κατά τη χρονική στιγμή/παράθυρο ταυτότητας).

8) Κατάσταση, επανάληψη και DLQ

8. 1 Καταληκτικά σημεία αποστολέα

'POST/webhooks/replay' - από τη λίστα 'event _ i list ή από το χρονικό παράθυρο.
'GET/webhooks/events/: id' - εμφάνιση της πηγαίας δέσμης και του ιστορικού των προσπαθειών.
DLQ: «νεκρά» γεγονότα (το όριο επαναπροσδιορισμού έχει εξαντληθεί) → χωριστή αποθήκευση, καταχωρίσεις.

8. 2 Τελικά σημεία λήψης

'GET/ webhooks/status/:event_id' -' seen = true/false ',' processed _ at ',' handler _ version '.
'POST/webhooks/ack' - (προαιρετική) επιβεβαίωση της χειροκίνητης επεξεργασίας από DLQ.

9) Συμβάσεις λάθους (απάντηση παραλήπτη)

http
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json
Retry-After: 120
X-Trace-Id: 4e3f...

{
"error": "invalid_state",
"error_description": "payout not found",
"trace_id": "4e3f..."
}

Συστάσεις: να επιστρέφετε πάντα έναν σαφή κώδικα και, ει δυνατόν, το «Retry-After». Μη επιστρέφετε λεπτομερή στοιχεία ασφαλείας.

10) Παρακολούθηση και SLO

• παράδοση p50/p95, ποσοστό επιτυχίας, retray/event, DLQ drop-rate, share 2xx/4xx/5xx, καθυστέρηση παραθύρου έως 2xx.

• επαλήθευση του ρυθμού αστοχίας (υπογραφή/χρόνος), του ρυθμού παράδοσης, του χειριστή καθυστέρησης p95, 5xx.

• Παράδοση: 99 ευρώ. 9% των γεγονότων λαμβάνουν 2xx <3 c p95 (μετά την πρώτη επιτυχημένη προσπάθεια).
• Κρυπτογραφική επαλήθευση: επικύρωση υπογραφής ≤ 2-5 ms p95.
• Dedup: 0 επαναλαμβανόμενες επιδράσεις (ακριβώς μία φορά αποτέλεσμα σε επίπεδο τομέα).

11) Ασφάλεια των δεδομένων και προστασία της ιδιωτικής ζωής

Μη μεταδίδετε PAN/PII στο σώμα του webhook. Χρησιμοποιήστε ταυτότητες και στη συνέχεια τραβήξτε για λεπτομέρειες κατά εγκεκριμένου API.
Μάσκα ευαίσθητων πεδίων σε κορμούς. αποθηκεύουν φορείς εκδηλώσεων μόνο στο ελάχιστο, με TTL.
Κρυπτογράφηση καταστημάτων DLQ και αναπαραγωγή.

12) Έκδοση και συμβατότητα

Έκδοση στην «έκδοση» (φάκελο) και στη διαμετακόμιση: «/webhooks/v1/πληρωμές ».
Τα νέα πεδία είναι προαιρετικά. απομάκρυνση - μόνο μετά την περίοδο «ηλιοβασίλεμα».
Τεκμηρίωση των αλλαγών στο αναγνώσιμο από το μηχάνημα changelog (για αυτόματους ελέγχους).

13) Περιπτώσεις δοκιμής (κατάλογος ελέγχου UAT)

• Επαναπροσδιορισμός του ίδιου «event _ id» → ένα αποτέλεσμα και '200' σε αντίγραφα.
• Υπογραφή: σωστό κλειδί, εσφαλμένο κλειδί, παλιό κλειδί (περιστροφή), «X-Timestamp» εκτός παραθύρου.
• Backoff: Παραλήπτης δίνει '429' with 'Retry-After' → σωστή παύση.
• Διάταξη: Γεγονότα '... μεταποιημένο 'έλα πριν'... δημιουργήθηκε '→ σωστή επεξεργασία/αναμονή.
• Βλάβη βάσης δεδομένων στο δέκτη μεταξύ εφέ και 'mark _ seen' → ατομικότητα/επανάληψη.
• DLQ και χειροκίνητη επανάληψη → επιτυχής παράδοση.
• Μαζική «καταιγίδα» (ο πάροχος στέλνει πακέτα) → χωρίς απώλεια, τα όρια δεν καταπνίγουν κρίσιμα.

14) Mini snippets

pseudo body = json(event)
canonical = ts + "\n" + "POST" + "\n" + path + "\n" + sha256(body)
sig = base64(hmac_sha256(secret, canonical))
headers = {"X-Timestamp": ts, "X-Event-Id": event.event_id, "X-Signature": "v1="+sig}
POST(url, body, headers)

pseudo assert abs(now - X-Timestamp) <= 300 assert timingSafeEqual(hmac(secret, canonical), sig)

if kv.exists("idemp:"+event_id): return 200

begin tx if kv.exists("idemp:"+event_id): commit; return 200 handle(event.data)        // доменная логика kv.set("idemp:"+event_id, "ok", ttl=259200)
commit return 200

15) Συχνά σφάλματα

Καμία απεξάρτηση → επαναλαμβανόμενα αποτελέσματα (διπλή αναπλήρωση/πληρωμές).
Υπογραφή χωρίς χρονοσφραγίδα/παράθυρο → επανάληψη ευπάθειας.
Αποθήκευση ενός μυστικού HMAC σε όλους τους εταίρους.
Απαντήσεις '200' πριν τον καθορισμό του αποτελέσματος → απώλεια συμβάντων σύγκρουσης.
Στοιχεία ασφαλείας «πλύσης» σε απαντήσεις/κούτσουρα.
Έλλειψη DLQ/επανάληψη - τα περιστατικά είναι άλυτα.

16) Φύλλο εξαπάτησης υλοποίησης

Ασφάλεια: HMAC v1 + 'X-Timestamp' + 'X-Event-Id', παράθυρο ≤ 5 λεπτά. mTLS/IP επιτρεπόμενη λίστα, όπως απαιτείται.
: 'event _ i ,' type ',' version ',' t , 'track', 'data'.
Παράδοση: τουλάχιστον μία φορά, backoff με jitter, 'Retry-After', DLQ + replay API.
Ταυτότητα: KV-cache 24-72 h, ατομική στερέωση της επίδρασης + 'mark _ seen'.
Παρατηρησιμότητα: παράδοση, υπογραφή, διπλές μετρήσεις. trace _ id.
Τεκμηρίωση: έκδοση, κωδικοί απόκρισης, παραδείγματα, κατάλογος ελέγχου UAT.

Επανάληψη σύνοψης

Τα επίμονα webhooks είναι χτισμένα πάνω σε τρεις φάλαινες: ένα υπογεγραμμένο φάκελο, τουλάχιστον μία φορά την παράδοση και idempotent επεξεργασία. Επισημοποιήστε το συμβόλαιο, ενεργοποιήστε HMAC/mTLS και το χρονικό παράθυρο, υλοποιήστε retrai + DLQ και επαναλάβετε, αποθηκεύστε idempotent ετικέτες και συλλάβετε εφέ ατομικά. Στη συνέχεια, τα γεγονότα παραμένουν αξιόπιστα ακόμη και με αστοχίες του δικτύου, κορυφές φορτίου και σπάνια «αντίγραφα της τύχης».