Webhuks առաքման երաշխիքները
Webhuki-ը asinhron ծանուցումներ է «համակարգից բաժանորդի» վրա HTTP (S)։ Ցանցը անվստահելի է, պատասխանները կորչում են, փաթեթները գալիս են կրկնօրինակներով կամ կարգից դուրս։ Այսպիսով, առաքման երաշխիքները կառուցվում են ոչ թե «TCP», այլ Webhuks-ի և հիբրիդային կուռքերի մակագրության մակարդակում։
Հիմնական նպատակն այն է, որ ապահովեք at-lement-once-առաքումը բանալիով (այնտեղ, որտեղ անհրաժեշտ է), բաժանորդին նյութեր տալ գաղափարական մշակման և վերականգնման գործիքի համար։
1) Երաշխիքների մակարդակները
Best-effect-ը միանգամյա փորձ է, առանց ռետրերի։ Ընդունելի է միայն «կարևոր» իրադարձությունների համար։
At-leport-once (խորհուրդ է) - հնարավոր են կրկնօրինակներ և out-of-order, բայց իրադարձությունը կփոխանցվի, եթե ստորագրողի հասանելիությունը խելացի ժամանակին։
Effectively-exactly-once-ը (ազդեցության մակարդակում), հասնում է idempotenty-ի և dedup-2019-ի համադրությունը բաժանորդի/ուղարկողի կողմում։ HTTP «exactly-once» տեղափոխության ժամանակ անհնար է։
2) Ուեբհուկի պայմանագիրը 'նվազագույն անհրաժեշտ
Վերնագրեր (օրինակ)
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) Կարգը և պատճառները
Բանալու կարգը 'երաշխիքը «չի հեռանում» միայն մեկ «partrone _ key» -ի ներսում (օրինակ ՝ «player _ id», «wallet _ id», «pult _ tx _ id»)։
Համաշխարհային կարգը երաշխավորված չէ։
Ուղարկողի կողմում շարքի հերթն է (մեկ սպառող/շարդինգ), ստացողի կողմում 'inbox s' (source, event _ id) "և ազդանշանային սպասումը բաց թողած" seq "։
Եթե բաց թողնեք քննադատական, տրամադրեք pox-API 'GET/events։ after = wwww.kpoint "կարգավիճակի համար" բռնել և խուսափել "։
4) Idempotenty և deduplication
Յուրաքանչյուր ուեբհուկ կրում է կայուն «X-Webhook-Id»։
Ստացողը պահպանում է «inbox (event _ id)»: PK - «source + event _ id»; կրկնությունները նշված են 71-op։
Կողմնակի էֆեկտները (ձայնագրությունը BD/դրամապանակներում) կատարվում են միայն մեկ անգամ առաջին «տեսիլքի» ժամանակ։
Թիմերի համար «էֆեկտով» օգտագործեք Idempotency-Key-ը և արդյունքների քեշը ռետրերի պատուհանի ժամանակ։
5) Retrai, backoff և պատուհաններ
Ռետրեյի քաղաքականությունը (հանրաքվեներ)
Կտրեք «5xx/timeout/connationerror/407-Systlict (retryable )/429»։
Մի ծախսեք «4xx» -ի վրա, բացի «409/423/429» (և միայն համաձայնեցված սեմանտիկայի դեպքում)։
Էքսպոնենցիալ backoff + fultjitter: 0։ 5s, 1s, 2s, 4s, 8s, … մինչև «max = 10-15 րոպե»; TTL պատուհանները 'օրինակ 72 ժամ։
Հարգել «Retry-After» -ը ստացողի մոտ։
Ունենալ ընդհանուր dedline '«ընդունել իրադարձությունը չհանձնված» և թարգմանել այն 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-ով ամբողջական մետաֆազով (paiload, վերնագրեր, սխալներ, փորձեր, հեշեր)։
Վեբ վահանակ/API-ը redrive-ի համար (կետային կրկնվող առաքում), որը ունի oporation աջ endpoint/գաղտնիքը։
Rate-limited redrive-ը և batch-redrive-ը գերակայությամբ։
7) Անվտանգություն
MTSA (հնարավորության դեպքում) կամ TFC 1։ 2+.
Մարմնի ստորագրությունը (HMAC գաղտնի per tenault/endpoint)։ Վերիֆիկացում
1. Դուրս բերել «t» (timestamp) վերնագրից, ստուգել սայթաքող պատուհանը (օրինակ ՝ 355 րոպե)։
8) Քվոտաներ, rate limits և արդարություն
Fox-Queue per ten.ru/www.scri.ru: Որպեսզի մեկ ստորագրողը/ստենանտը չնշի ընդհանուր փամփուշտը։
Քվոտաները և burst-limits առաջացող կոմպոզիցիայի և per-endpoint-ի վրա։
Արձագանքը '429': Կարդալ 'Retry-After', հոսքը։ երկարատև հավաքման ժամանակ 'degrade (միայն կրիտիկական իրադարձությունների ուղարկումը)։
9) Կյանքի ցիկլը
Register/Verify: POST endpoint challenge/response կամ out-of-band ապացույց։
Least (ցանկությամբ), ստորագրությունը գործում է մինչև «valid _ to»; շեղումը ակնհայտ է։
Test ping 'արհեստական իրադարձություն ստուգելու համար, նախքան հիմնական տոպիկների միացումը։
Secret rotation: `current_secret`, `next_secret` с `switch_at`.
Health-փորձարկումներ 'HEAD/GET-ը latency և TMS-ի ստուգմամբ։
10) Սխեմաների էվոլյուցիան (իրադարձությունների տարբերակները)
Էվոլյուցիան intitive (MINOR տարբերակը API), breaking-ը նոր տեսակի է։
Սխեմաների գրանցումը (JSON-Schema/Avro/Eurobuf) + ավտոմատ վալիդացիա ուղարկելուց առաջ։
Իրադարձության տեսակի տարբերակումը '"payment. authorized. v1` → `…v2`.
«X-Event-Type» վերնագիրը և «schema _ version» դաշտը մարմնի մեջ, երկուսն էլ պարտադիր են։
11) Դիտարկումը և SLO-ն
Մետրիկները (օրինակ/տենանտու/ստորագրողի)
`deliveries_total`, `2xx/4xx/5xx_rate`, `timeout_rate`, `signature_fail_rate`.
«attempult _ avg», «p50/p95/p99 _ medivery _ latency _ latency» (հրատարակությունից մինչև 2xx)։
`dedup_rate`, `out_of_order_rate`, `dlq_rate`, `redrive_success_rate`.
`queue_depth`, `oldest_in_queue_ms`, `throttle_events`.
SLO (հանրաքվե)
Առաքումների մասնաբաժինը 60 c (p95) 99 է։ Հինգ տոկոսը կրիտիկական իրադարձությունների համար։
DLQ ≤ 0. 1 տոկոսը 24 ռուբլիով
Signature failures ≤ 0. 05%.
Логи/трейсинг: `event_id`, `partition_key`, `seq`, `attempt`, `endpoint`, `tenant_id`, `schema_version`, `trace_id`.
12) Ուղարկողի հանրաքվե ալգորիթմը
1. Գրեք իրադարձությունը գործարքային բլոկում։
2. Որոշել partection _ key և seq; տեղադրել։
3. Worker վերցնում է բանալին, ձևավորում է հարցումը, ստորագրում, ուղարկում թայմաուտների հետ (connational/read)։
4. «2xx» - ընդունել առաքյալներին, ամրագրել լատենտությունը և seq-chekpoint։
5. «429/5xx/timeout» -ի դեպքում, ըստ քաղաքականության։
6. TTL-ով DLQ-ն և ալերտը։
13) Հանրաքվե մշակողը (ստացողը)
1. Ընդունել հարցումը, ստուգել TFC/www.o։
2. Ստորագրության վալիդացիան և ժամանակի պատուհանները։
3. Արագ ACK 2xx (տեղական inbox/հերթում սինխրոն ձայնագրությունից հետո)։
4. Asinhrone worker կարդում է «inbox», ստուգում է «event _ id» (dedup), անհրաժեշտության դեպքում, պատվիրում է «seq 'ներսում»։
5. Կատարում է էֆեկտներ, գրում է «set/seq chekpoint» reconcile-ի համար։
6. Սխալի դեպքում տեղական գետերն են։ «թունավոր» առաջադրանքները կատարվում են տեղական DLQ-ի ալտերտերով։
14) Reconcile (պուլլ-2019)
«Անխուսափելի» կոմպոզիցիաների համար
`GET /events? partance _ key =... & after _ seq =... & limit =... "- տալ բոլոր բաց թողած։
Token-chekpoint: 'after = opaque _ token' seq-ի փոխարեն։
Idempotent redelivery: Նույն «event _ id», նույն ստորագրությունը նոր 't'։
15) Օգտակար վերնագրեր և վերնագրեր
2xx - ընդունեց (նույնիսկ եթե բիզնես մշակումը ավելի ուշ)։
410 Gone - endpoint փակված է (ուղարկողը դադարում է առաքումը և սահմանափակում է բաժանորդագրությունը որպես «արխիվ»)։
4.9/423 - ռեսուրսի ժամանակավոր արգելափակումը retram-ի սահմանափակում է։
429 - չափազանց հաճախ trotttl և backoff։
400/401/403/404 - միգրացիոն սխալ; կանգնեցնել գետերը, բացել հյուսետը։
16) Multi-tenant և տարածաշրջանները
Առանձին գծեր և limits per tenae/endpoint։
Euresidency: ուղարկումը տվյալների տարածքից; «X-Tenault», «X-Region» վերնագրերի միջոցով։
Ձախողումների մեկուսացումը 'մեկ բաժանորդի նվազումը չի ազդում մյուսների վրա (separate poope)։
17) Թեստավորում
Euract tes.ru: մարմնի/ստորագրությունների ֆիքսված օրինակներ, վալիդացիայի ստուգում։
Chaos: dom/կրկնօրինակներ, shuffle, ցանցի ուշացում, «RST», «TIM»։
Load: burst փոթորիկ, p95/p99։
Տե՛ ս 'հակատիպը, հնացած timestamp, սխալ գաղտնիքները, ռոտացիան։
DR/Replay: զանգվածային redrive DLQ-ից մեկուսացված պատում։
18) Պլեյբուկի (runbooks)
1. Աճը 'signature _ fail _ rate'
Ստուգել «toler.ru» -ի ավարտված ժամացույցի թռիչքը, գաղտնիքների ռոտացիան։ ժամանակավորապես ներառել «dult secret»։
2. Երիկամների հերթը («oldest _ in _ queue _ enter»)
Բարձրացնել վորկերները, ներառել կրիտիկական տոպիկների գերակայությունը, ժամանակավորապես նվազեցնել «աղմկոտ» տեսակների հաճախությունը։
3. Փոթորիկ '429' ստորագրողի մոտ
Միացրեք տրոտլինգը և դադարները փորձերի միջև։ տեղափոխել ավելի քիչ քննադատական տեսակներ։
4. Զանգվածային «5xx»
Բացել circuit-breaker կոնկրետ endpoint-ի համար, տեղափոխել www.er & batch ռեժիմը։ ստորագրողի ազդանշանը։
5. DLQ լրացումը
Կանգնեցնել քննադատական հրապարակումը, ներառել batch-redrive ցածր RPS-ով, բարձրացնել ալտերը ստորագրությունների սեփականատերերին։
19) Տիպիկ սխալներ
Սինխրոն ծանր բուժումը մինչև 2xx-ի պատասխանը ռետրաններ և կրկնօրինակներ։
Մարմնի/պատուհանի ստորագրություններ չկան, որոնք խոցելիություն են առաջացնում փոխարինելու/կտրելու համար։
«Event _ id» և «inbox» -ի բացակայությունը անհնար է դարձնել գաղափարախոսություն։
«Համաշխարհային կարգի» փորձը հավիտենական արգելափակում է հերթերը։
Retrai առանց jitter/limits www.ru (thundering herd)։
Միակ ընդհանուր փամփուշտը բոլոր բաժանորդների վրա «աղմկոտ» տեղադրում է բոլորին։
20) Չեկ թուղթ մինչև վաճառելը
- Պայմանագիրը '"event _ id", "partence _ key", "seq", "event _ type. VN ', HMAC ստորագրությունը և timestamp։
- Ուղարկողը 'wwww.box, հեռուստացույց, backoff + jitter, TTL, DLQ և redrive։
- Ստացողը 'արագ ձայնագրություն inbox + 2xx; իդեմենտային վերամշակում; Տեղական DLQ-ն։
- Անվտանգություն ՝ TSA, ստորագրություններ, հակատիպեր, dom-secret, նավարկություն։
- Քվոտաներ/լիմիտներ ՝ fox-queue per tenae/endpoint, հարգանք «Retry-After»։
- Reconcile API և chekpoints; նախատեսված է բաժանորդների համար։
- Դիտարկումը 'p95/հոսքեր/սխալներ/DLQ, ուղին' event _ id "։
- Իրադարձությունների տարբերակումը և սխեմաների էվոլյուցիայի քաղաքականությունը։
- Պլեյբուկները բացատրում են գլոբալ դադարի/ցրտահարության «կոճակը»։
Եզրակացություն
Հուսալի Webhuks-ը HTTP-ի վերևում է, ոչ միայն «POST-ը JSON-ի հետ»։ Հստակ պայմանագիրը (ID, կարգադրության բանալին, ստորագրությունը), impter-ը, jitter-ը, արդար հերթը և լավ կարգավորված պլեյբուսները վերածում են «լավագույն դեպքի» կանխատեսելի և չափված առաքման մեխանիզմի։ Կառուցեք at-leport-once + կարգը + reconcile բանալին, և համակարգը հանգիստ գոյատևելու է ցանցը, բեռի պիկը և մարդկային սխալները։