Garanții de livrare prin broșură web

Webhookurile sunt notificări asincrone de la sistem la abonat prin HTTP (S). Rețeaua nu este fiabilă: răspunsurile sunt pierdute, pachetele vin în duplicate sau în afara ordinii. Prin urmare, garanțiile de livrare nu sunt construite „peste TCP”, ci la nivelul protocolului webhook și idempotency domeniu.

Scopul cheie: de a furniza cel puțin o dată de livrare cu comanda la cheie (acolo unde este necesar), de a oferi abonatului materiale pentru prelucrarea idempotent și un instrument de reconciliere pentru restaurări.

1) Niveluri de garanție

Cel mai bun efort - o încercare unică, fără retras. Acceptabil doar pentru evenimente „neimportante”.
Cel puțin o dată (recomandat) - duplicate și out-of-order sunt posibile, dar evenimentul va fi livrat cu condiția ca abonatul este disponibil într-un timp rezonabil.
Efectiv-exact-o dată (la nivelul efectului) - realizat printr-o combinație de idempotență și de stocare dedup la partea abonat/expeditor. Transportul „exact o dată” HTTP nu este posibil.

2) Contract de broșură web: minim necesar

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
}

Cerința pentru destinatar: răspundeți rapid „2xx” după tamponarea și validarea semnăturii și faceți procesarea asincronă a afacerii.

3) Ordinea și cauzalitatea

Comanda cheie: garanția „nu va pleca” doar în interiorul unei singure 'partition _ key' (de ex. 'player _ id',' wallet _ id', 'psp _ tx _ id').
Ordinea globală nu este garantată.
Pe partea expeditorului există o coadă cu serializarea prin cheie (un consumator/sharding), pe partea destinatarului există un inbox cu „(sursă, event_id)” și opțional așteaptă lipsa „seq”.

În cazul în care lacunele sunt critice - oferi pull' API 'GET/evenimente? after = checkpoint 'pentru „prinde și consultă”.

4) Idempotență și deduplicare

Fiecare cârlig web poartă un stabil "X-Webhook-Id'.
Destinatarul stochează "inbox (event_id)": PK - "sursă + event_id'; repetă → nu-op.
Efectele secundare (scrierea în baza de date/portofel) se efectuează o singură dată atunci când evenimentul este „văzut” pentru prima dată.
Pentru comenzi cu efect, utilizați Idempotency-Key și cache-ul rezultat pe durata ferestrei retray.

5) Retrai, backoff și ferestre

• Recalificați-vă la '5xx/timeout/connection error/409-Conflict (retryable )/429'.
• Nu retractați pe „4xx”, cu excepția „409/423/429” (și numai cu semantică consistentă).
• Backoff exponențial + jitter complet: 0. 5s, 1s, 2s, 4s, 8s,... până la 'max = 10-15 min'; Ferestre retractabile TTL: de exemplu, 72 de ore.
• Respectați „Retry-After” de la destinatar.
• Aveți un termen comun: „recunoașteți evenimentul ca nefiind livrat” și transferați-l la 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 - „cimitir” de evenimente otrăvitoare sau expirate TTL cu informații complete meta (sarcină utilă, antete, erori, încercări, hash-uri).
Consola Web/API pentru Redrive (punct de re-livrare) cu endpoint opțional/editare secretă.
Rata-limitat redrive și lot-redrive prioritizate.

7) Siguranță

mTLS (dacă este posibil) sau TLS 1. 2+.

1. Extrageți 't "(marcaj de timp) din antet, verificați fereastra glisantă (de exemplu, ± 5 minute).

8) Cote, limite de rată și capitaluri proprii

Fair-Queue per chiriaș/abonat: astfel încât un abonat/chiriaș să nu înscrie piscina generală.
Cote și limite de spargere pentru traficul de ieșire și pentru fiecare punct final.
Reacție la „429”: onoare „Retry-After”, flux de troli; pentru limitarea pe termen lung - degrade (trimiterea doar a tipurilor critice de evenimente).

9) Ciclul de viață al abonamentului

Înregistrați-vă/Verificați: punctul final POST → provocare/răspuns sau confirmare în afara benzii.
Leasing (opțional): semnătura este valabilă până la 'valid _ to'; prelungire - explicit.
Rotație secretă: 'current _ secret', 'next _ secret' с 'switch _ at'.
Test ping: un eveniment artificial pentru a testa traseul înainte de a porni subiectele principale.
Mostre de sănătate: HEAD/GET periodic cu latență și verificarea profilului TLS.

10) Evoluția schemelor (versiuni de evenimente)

Versioning tip eveniment: 'plata. autorizat. v1 '→'... v2 '.
Evolutie - aditiv (domenii noi → versiuni API MINORE), rupere → un nou tip.
Registru schemă (JSON-Schema/Avro/Protobuf) + validare automată înainte de depunere.
Antetul „X-Event-Type” și câmpul „schema _ version” din corp sunt ambele necesare.

11) Observabilitate și SLO

• 'deliveries _ total', '2xx/4xx/5xx _ rate', 'timeout _ rate', 'signature _ fail _ rate'.
• 'attempts _ avg', 'p50/p95/p99 _ delivery _ latency _ ms' (publicați la 2xx).
• 'dedup _ rate', 'out _ of _ order _ rate', 'dlq _ rate', 'redrive _ success _ rate'.
• 'queue _ adancime', 'best _ in _ queue _ ms',' throttle _ events'.

• Ponderea livrărilor ≤ de 60 s (p95) - 99. 5% pentru evenimente critice.
• DLQ ≤ 0. 1% în 24 de ore
• Eşecuri ale semnăturii ≤ 0. 05%.

Логи/трейсинг: 'event _ id',' partition _ key ',' seq ',' trace ',' endpoint ',' tenant _ id', 'schema _ version', 'trace _ id'.

12) Algoritmul de referință al expeditorului

1. Scrieți evenimentul în outbox-ul tranzacțional.
2. Definiți partition_key și seq; coadă.
3. Lucrătorul ia prin cheie, formează o cerere, semnează, trimite cu timeout-uri (conectați/citiți).
4. Cu '2xx' - recunoașteți ca livrat, fixați latența și punctul de control seq.
5. Cu '429/5xx/timeout' - retragere în conformitate cu politica.
6. De TTL → DLQ și alertă.

13) Procesor de referință (receptor)

1. Acceptați cererea, verificați TLS/proto.
2. Validarea ferestrei de semnătură și de timp.
3. Rapid ACK 2xx (după scrierea sincronă la inbox/coadă locală).
4. Lucrătorul asincron citește „inbox”, verifică „event _ id' (bunicul), dacă este necesar, ordinele prin” seq 'inside „partition _ key”.
5. Realizează efecte, scrie „offset/seq checkpoint” pentru reconciliere.
6. În caz de eroare - retribuții locale; sarcini „otrăvitoare” → DLQ locale cu alerte.

14) Reconciliere (buclă de piscină)

• "GET/evenimente? partition_key=...&after_seq=...&limit=...' - pentru a da toate ratat.
• Punct de control token: 'after = opaque _ token' în loc de seq.
• Redelivery Idempotent: aceeași 'event _ id', aceeași semnătură pe noul' t '.

15) Rubrici și coduri utile

2xx - acceptat (chiar dacă procesarea afacerii este mai târziu).
410 Gone - punctul final este închis (expeditorul oprește livrarea și marchează abonamentul ca „arhivat”).
409/423 - blocarea temporară a reluării → resurselor este rezonabilă.
429 - prea des → accelerație și backoff.
400/401/403/404 - eroare de configurare; opriţi retraiul, deschideţi biletul.

16) Multi-chiriaș și regiuni

Cozi individuale și limite per chiriaș/punct final.
Rezidența datelor: trimiterea datelor din regiune; anteturile end-to-end „X-Tenant”, „X-Region”.
Izolarea eșecurilor: căderea unui abonat nu afectează restul (piscine separate).

17) Testarea

Teste de contract: exemple fixe de organisme/semnături, verificarea validării.
Haos: drop/duplicate, ordine de amestecare, întârzieri în rețea, erori 'RST', 'TLS'.
Sarcină: explozie-furtună, măsurată p95/p99.
Securitate: anti-reluare, timestamp depășit, secrete greșite, rotație.
DR/Replay: Masa redrive de la DLQ în stand izolat.

18) Cărți de joc (runbooks)

1. Creștere 'semnătură _ fail _ ratee'

Verificați deriva ceasului, „toleranța” expirată, rotația secretelor; temporar permite „dublu secret”.

2. Coada îmbătrânește ('oldest _ in _ queue _ ms' ↑)

Creșterea lucrătorilor, permite prioritizarea subiectelor critice, reduce temporar frecvența tipurilor „zgomotoase”.

3. Storm '429' la abonat

Activați accelerarea și pauzele între încercări; schimbați tipurile de evenimente mai puțin critice.

4. Masa „5xx”

Deschideți întrerupătorul pentru un anumit punct final, comutați pentru a amâna & lot; semnal către abonat.

5. Populați DLQ

Opriți publicarea non-critică, activați lotul-redrive cu RPS scăzut, ridicați alerte proprietarilor de abonamente.

19) Erori tipice

Procesare sincronă grea la răspuns 2xx → retribuiri și duplicate.
Nici o semnătură fereastră corp/timp → de substituție/reluare vulnerabilitate.
Absența → 'event _ id' și' inbox 'nu poate fi făcută idempotent.
O încercare de „ordine globală” → blochează eterna coadă.
Se retrage fără jitter/limite → intensificarea incidentelor (turmă tunătoare).
O singură piscină comună pentru toți abonații → „zgomotos” pune toată lumea.

20) Lista de verificare pre-vânzare

• Contract: 'event _ id',' partition _ key ',' seq ',' event _ type. vN ', semnătura HMAC şi marcajul temporal.
• Expeditor: outbox, serializare după cheie, retroactive cu backoff + jitter, TTL, DLQ și redrive.
• Destinatar: scrieți rapid la inbox + 2xx; tratament idempotent; DLQ local.
• Securitate: TLS, semnături, anti-reluare, dual-secret, rotație.
• Cote/limite: coadă echitabilă pentru fiecare chiriaș/punct final, respect 'Retry-After'.
• Reconciliază API-urile și punctele de control; documentație pentru abonați.
• Observabilitate: p95/threads/errors/DLQ, trace to 'event _ id'.
• Event versioning and schema evolution policy.
• Playbook-uri incidente și butonul global pauză/dezgheț.

Concluzie

Cărțile web de încredere sunt un protocol pe partea de sus a HTTP, nu doar "POST cu JSON. "Un contract clar (ID, cheie de comandă, semnătură), idempotență, retray cu jitter, coadă corectă și cărți de redare bine depanate transformă cel mai bun caz într-un mecanism de livrare previzibil și măsurabil. Construiți cel puțin o dată + ordine cheie + reconciliați, iar sistemul va supraviețui calm rețelei, vârfurilor de încărcare și erorilor umane.