Webhuklary eltmegiň kepillikleri

Webhuklar - HTTP (S) arkaly "ulgamdan abonente" asinxron habarnamalary. Tor ygtybarly däl: jogaplar ýitýär, bukjalar dublikat ýa-da tertipden daşary gelýär. Şonuň üçin eltip bermek kepillikleri "TCP boýunça" däl-de, webhuklaryň we domen idempotentliginiň teswirnamasy derejesinde gurulýar.

Esasy maksat: açar boýunça (zerur bolan ýerlerde) at-least-once eltip bermegi üpjün etmek, abonente dempotent gaýtadan işlemek üçin materiallary we dikeldiş üçin reconcile guralyny bermek.

1) Kepillikleriň derejeleri

Best-effort - retrajsyz bir gezeklik synanyşyk. Diňe "möhüm däl" wakalar üçin kabul ederlikli.
At-least-once (maslahat berilýär) - dublikatlar we out-of-order mümkin, ýöne waka abonent üçin amatly möhletde elýeterli bolan ýagdaýynda getiriler.
Effectively-exactly-once (effekt derejesinde) - abonentiň/iberijiniň tarapynda idempotentlik we dedup-ammar kombinasiýasy arkaly gazanylýar. Ulagda HTTP "exactly-once" mümkin däl.

2) Webhuk şertnamasy: iň az zerur

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
}

Alyja bildirilýän talap: goluň buferirlenenden we tassyklanandan soň çalt '2xx' jogap bermek, işewürlik işini bolsa asinhron etmek.

3) Tertibi we sebäpliligi

Açar tertibi: kepillik diňe bir 'partition _ key' içinde "gitmez" (mysal üçin, 'player _ id', 'wallet _ id', 'psp _ tx _ id').
Global tertip kepillendirilmeýär.
Iberijiniň tarapynda - açar boýunça seriýalaşdyrylan nobat (bir sarp ediji/şarding), alyjynyň tarapynda - inbox c '(source, event_id)' we goşmaça sypdyrylanlara garaşmak 'seq'.

Eger geçişler möhüm bolsa, pull-API 'GET/events beriň? after = checkpoint '"ýetmek we barlamak" statusy üçin.

4) Idempotentlik we duplikasiýa

Her webhuk durnukly 'X-Webhook-Id' göterýär.
Alyjy 'inbox (event_id)' saklaýar: PK - 'source + event_id'; → no-op.
Zyýanly täsirler (DB/gapjyga ýazylmak) wakanyň ilkinji "görüşinde" diňe bir gezek ýerine ýetirilýär.
"Effekt" buýruklary üçin "Idempotency-Key" we "Retrais" penjiresiniň wagty üçin netije keşini ulanyň.

5) Retraýalar, backoff we penjireler

• '5xx/timeout/connection error/409-Conflict (retryable )/429' -da retra.
• '409/423/429' -dan başga '4xx' -a geçilmez (we diňe ylalaşylan semantikada).
• Eksponensial backoff + full jitter: 0. 5s, 1s, 2s, 4s, 8s, … 'max = 10-15 min' -e çenli; TTL retraý penjireleri: mysal üçin 72 sagat.
• Alyjynyň 'Retry-After' -ine hormat goýmak.
• "Wakany gowşurylmady diýip ykrar etmek" we ony DLQ-e geçirmek.

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 - doly metainformasiýa (paiload, sözbaşylar, ýalňyşlyklar, synanyşyklar, eşler) bilen zäherli ýa-da TTL-den geçen wakalaryň "gonamçylygy".
Web konsol/API redrive (nokat gaýtadan eltip bermek) üçin endpoint/syr opsiýa düzedişi bilen.
Rate-limited redrive we batch-redrive ileri tutulýan ugur bilen.

7) Howpsuzlyk

mTLS (mümkin boldugyça) ýa-da TLS 1. 2+.

1. Sözbaşydan 't' (timestamp) çykarmak, süýşýän penjiräni barlamak (mysal üçin ± 5 minut).

8) Kwotalar, rate limits we adalat

Fair-Queue per tenant/subscriber: bir abonentiň/tenantyň umumy howuzy urmazlygy üçin.
Çykýan traffik we per-endpoint üçin kwotalar we burst-çäkler.
'429' -a reaksiýa: 'Retry-After' okamak, trotlet akymy; uzak möhletli çäklendirmede - degrade (diňe möhüm hadysalary ibermek).

9) Abuna ýazylmagyň durmuş sikli

Register/Verify: POST endpoint → challenge/response ýa-da out-of-band tassyklamasy.
Lease (isleg boýunça): gol 'valid _ to' -e çenli hereket edýär; uzaltmak - aýdyň.
Secret rotation: `current_secret`, `next_secret` с `switch_at`.
Test ping: esasy topikleri açmazdan ozal marşruty barlamak üçin emeli waka.
Saglyk synaglary: latency we TLS profilini barlamak bilen wagtal-wagtal HEAD/GET.

10) Shemalaryň ewolýusiýasy (wakalaryň wersiýasy)

Wakanyň görnüşi: 'payment. authorized. v1` → `…v2`.
Ewolýusiýa - additive (täze meýdanlar → API MINOR wersiýasy), breaking → täze görnüş.
Shemalaryň sanawy (JSON-Schema/Euro/Protobuf) + iberilmezden öň awtomatiki tassyklama.
Bedende 'X-Event-Type' sözbaşy we 'schema _ version' meýdany - ikisi hem hökmanydyr.

11) Synlamak we SLO

• `deliveries_total`, `2xx/4xx/5xx_rate`, `timeout_rate`, `signature_fail_rate`.
• 'attempts _ avg', 'p50/p95/p99 _ delivery _ latency _ ms' (neşirden 2xx çenli).
• `dedup_rate`, `out_of_order_rate`, `dlq_rate`, `redrive_success_rate`.
• `queue_depth`, `oldest_in_queue_ms`, `throttle_events`.

• Eltip bermegiň paýy ≤ 60 c (p95) - 99. 5% möhüm wakalar üçin.
• DLQ ≤ 0. 24 sagatda 1%
• Signature failures ≤ 0. 05%.

Логи/трейсинг: `event_id`, `partition_key`, `seq`, `attempt`, `endpoint`, `tenant_id`, `schema_version`, `trace_id`.

12) Iberijiniň salgylanma algoritmi

1. Wakany geleşik outbox -a ýazyň.
2. partition_key we seq kesgitlemek; nobata goýmak.
3. Worker açar boýunça alýar, haýyşy emele getirýär, gol çekýär, wagt bilen iberýär (connect/read).
4. '2xx' bolanda - gowşuryldy diýip ykrar etmek, gizlinligi we seq-çek nokadyny düzetmek.
5. Haçan '429/5xx/timeout' - syýasata laýyklykda retrai.
6. TTL → DLQ we alert boýunça.

13) Salgylanma prosessory (alyjy)

1. Soragy kabul et, TLS/proto barlaň.
2. Gol we wagt penjiresini tassyklamak.
3. Çalt ACK 2xx (lokal inbox/nobata sinhron ýazylandan soň).
4. Asinxron worker 'inbox' okaýar, 'event _ id' -ni (dedupy) barlaýar, zerur bolsa 'seq' içindäki 'partition _ key' -ni tertipleşdirýär.
5. Täsirleri ýerine ýetirýär, reconcile üçin "offset/seq checkpoint" ýazýar.
6. Ýalňyşlyk ýüze çykan halatynda - ýerli retralar; "zäherli" meseleler → alertler bilen lokal DLQ.

14) Reconcile (pull-kontury)

• `GET /events? partition_key=...&after_seq=...&limit=...' - sypdyrylanlaryň hemmesini bermek.
• "seq" ýerine 'after = opaque _ token' belgi.
• Idempotent redelivery: şol bir 'event _ id', täze 't' boýunça şol bir gol.

15) Peýdaly sözbaşylar we kodlar

2xx - kabul edildi (iş gaýtadan işlenenden soň hem).
410 Gone - endpoint ýapyldy (iberiji eltip bermegi bes edýär we abunalygy "arhiwe" diýip belleýär).
409/423 - çeşmäniň wagtlaýyn petiklenmegi → retrai akyl.
429 - gaty ýygy → trottl we backoff.
400/401/403/404 - konfigurasiýa ýalňyşlygy; retraýlary duruzmak, bilet açmak.

16) Köp tenant we sebitler

Aýry-aýry nobatlar we per tenant/endpoint çäkleri.
Data residency: maglumatlary sebitden ibermek; "X-Tenant", "X-Region" sözbaşylary.
Şowsuzlyklaryň izolýasiýasy: bir abonentiň ýykylmagy beýlekilere täsir etmeýär (separate pools).

17) Synag

Contract tests: tel/gollaryň kesgitlenen mysallary, tassyklamany barlamak.
Chaos: drop/dublikatlar, shuffle tertibi, toruň gijikdirilmegi, 'RST', 'TLS' - ýalňyşlyklar.
Ýüklemek: burst-tupan, p95/p99.
Howpsuzlyk: anti-gürlemek, köne timestamp, nädogry syrlar, aýlaw.
DR/Replay: izolirlenen stendde DLQ-den köpçülikleýin redrive.

18) Oýun kitaplary (runbooks)

1. 'signature _ fail _ rate'

Sagadyň süýşmegini, geçen 'tolerans', syrlaryň aýlanmagyny barlamak; "dual secret" -i wagtlaýyn açyň.

2. Nobat ýaşarýar ('oldest _ in _ queue _ ms' ↑)

Workerleri köpeltmek, möhüm topikleriň ileri tutulmagyny goşmak, "şowhunly" görnüşleriň ýygylygyny wagtlaýyn azaltmak.

3. Abonent üçin tupan '429'

Synanyşyklaryň arasynda trottling we arakesmeleri açyň; wakalaryň az kritiki görnüşlerini göçürmek.

4. Köpçülikleýin '5xx'

Belli bir endpoint üçin circuit-breaker açyň, defer & batch re modeimine geçiriň; abonente signal.

5. DLQ doldurmak

Tankydy däl neşirleri duruzmak, pes RPS bilen batch-redrive açmak, abuna eýelerine aladalary ýokarlandyrmak.

19) Adaty ýalňyşlyklar

2xx → retrailer we dublikatlar jogap berýänçä sinhron agyr gaýtadan işlemek.
Beden/Wagt penjiresi goly ýok → Çalyşma/Replay gowşaklygy.
'event _ id' we 'inbox' → ýok.
"Global tertip" synanyşygy → nobatlaryň baky petiklenmegi.
Jitter/limitsiz retraýalar → hadysany güýçlendirmek (thundering herd).
Ähli abonentler üçin bir umumy howuz → "şowhunly" hemmäni goýýar.

20) Azyk önüminden öň çek-sanawy

• Şertnama: 'event _ id', 'partition _ key', 'seq', 'event _ type. vN ', HMAC we timestamp goly.
• Iberiji: outbox, açar seriýalizasiýasy, backoff + jitter, TTL, DLQ we redrive bilen retralar.
• Alyjy: inbox + 2xx-a çalt ýazylmak; idempotent gaýtadan işlemek; lokal DLQ.
• Howpsuzlyk: TLS, gollar, anti-rap, dual-secret, aýlaw.
• Kwotalar/çäkler: fair-queue per tenant/endpoint, hormat 'Retry-After'.
• Reconcile API we barlag nokatlary; abonentler üçin resminamalar.
• syn edilişi: p95/akymlar/ýalňyşlyklar/DLQ, 'event _ id' -den yzarlamak.
• Wakalaryň wersiýalanmagy we shemalaryň ewolýusiýa syýasaty.
• Wakalaryň oýun kitaplary we global arakesme/eroziýa "düwmesi".

Netije

Ygtybarly webhuklar diňe "JSON bilen POST" däl, HTTP-iň üstündäki teswirnamadyr. Anyk şertnama (ID, tertip açary, gol), idempotentlik, jitter bilen retraýalar, adalatly nobat we oňat düzülen pleýbuklar "iň gowy-iş" -y öňünden aýdyp boljak we ölçäp boljak eltiş mehanizmine öwürýär. At-least-once + açar tertibi + reconcile guruň we ulgam tordan, ýüküň iň ýokary derejelerinden we adam ýalňyşlyklaryndan arkaýyn halas bolar.