Кафолатҳои таҳвили Webhook

Webhooks огоҳиномаҳои асинхронӣ ба муштарӣ тавассути HTTP (S) мебошанд. Шабака беэътимод аст: ҷавобҳо гум мешаванд, пакетҳо бо нусхабардорӣ ё корношоям мешаванд. Аз ин рӯ, кафолатҳои таҳвил на "бар TCP", балки дар сатҳи протоколи webhook ва idempotency домейн сохта мешаванд.

Ҳадафи асосӣ: таъмин намудани ҳадди аққал як маротиба бо фармоиш аз рӯи калид (дар ҳолати зарурӣ), додани маводи муштарӣ барои коркарди idempotent ва асбоби мусолиҳа барои барқарорсозӣ.

1) Сатҳи кафолат

Кӯшиши беҳтарин - кӯшиши якдафъаина, бидуни бозгашт. Танҳо барои рӯйдодҳои "муҳим" қобили қабул аст.
Ҳадди аққал як маротиба (тавсия дода мешавад) - нусхабардорӣ ва фармоишӣ имконпазир аст, аммо чорабинӣ ба шарте расонида мешавад, ки муштарӣ дар мӯҳлати муносиб дастрас бошад.
Самаранок - як маротиба (дар сатҳи эффект) - бо омезиши idempotency ва нигоҳдории dedup дар ҷониби муштарӣ/ирсолкунанда ба даст оварда мешавад. Нақлиёти HTTP "маҳз як маротиба" имконнопазир аст.

2) Шартномаи Webhook: ҳадди аққал талаб карда мешавад

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) Тартиб ва сабабҳо

Тартиби асосӣ: кафолати "танҳо" дар дохили як "partition _ key" (масалан, тарк намекунад) 'player _ id', 'wallet _ id', 'psp _ tx _ id').
Тартиби глобалӣ кафолат дода намешавад.
Дар тарафи ирсолкунанда навбат бо сериализатсия бо калид мавҷуд аст (як истеъмолкунанда/якбора), дар тарафи қабулкунанда паёмдони дорои '(манбаъ, event_id)' мавҷуд аст ва ихтиёран интизори гум шудани 'seq' мебошад.

Агар холигоҳҳо муҳим бошанд - pull-API 'GET/чорабиниҳоро таъмин кунед? пас аз = нуқтаи назоратӣ 'барои "гирифтан ва машварат кардан".

4) Idempotency ва deduplication

Ҳар як webhook дорои 'X-Webhook-Id' мебошад.
Қабулкунанда 'паёмдони (event_id)' -ро нигоҳ медорад: PK - 'манбаъ + event_id'; такрор → no-op.
Таъсири иловагӣ (навиштан ба пойгоҳи додаҳо/ҳамён) танҳо як маротиба ҳангоми бори аввал "дида шудан" иҷро карда мешавад.
Барои фармонҳои таъсирбахш, Idempotency-Key ва кэши натиҷаро дар тӯли равзанаи бозсозӣ истифода баред.

5) Retrai, backoff ва тирезаҳо

• Бозомӯзӣ ба '5xx/timeout/connection error/409-Conflict (такрорӣ )/429'.
• Аз '4xx' даст накашед, ба истиснои '409/423/429' (ва танҳо бо семантикаи пайваста).
• Бозгашти экспоненсиалӣ + jitter пурра: 0. 5s, 1s, 2s, 4s, 8s,... то 'max = 10-15 дақиқа'; Тирезаҳои бозсозии TTL: масалан, 72 соат.
• Эҳтиром 'Retry-After' аз гиранда.
• Мӯҳлати умумӣ дошта бошед: "ҳодисаро ҳамчун таслим эътироф накунед" ва онро ба DLQ интиқол диҳед.

yaml retry:
initial_ms: 500 multiplier: 2.0 jitter: full max_delay_ms: 900000 ttl: 72h retry_on: [TIMEOUT, 5xx, 429]

6) DLQ i redrive

DLQ - "қабристон" -и ҳодисаҳои заҳролуд ё TTL, ки ба итмом расидаанд, бо маълумоти пурраи мета (сарборӣ, сарлавҳаҳо, хатогиҳо, кӯшишҳо, ҳашҳо).
Веб-консол/API барои redrive (интиқоли нуқта) бо нуқтаи ихтиёрӣ/таҳрири махфӣ.
Redrive-и маҳдуд ва redrive-партия афзалият дода шуд.

7) Бехатарӣ

MTLS (агар имконпазир бошад) ё TLS 1. 2+.

1. Иқтибос накунед '(timestamp) аз сарлавҳа, тирезаи слайдро санҷед (масалан, ± 5 дақиқа).

8) Квотаҳо, маҳдудиятҳои меъёрҳо ва сармоя

Fair-Queue ба як иҷорагир/муштарӣ: то ки як муштарӣ/иҷорагир ҳавзи умумиро баҳо надиҳад.
Квотаҳо ва маҳдудиятҳо барои трафики баромад ва нуқтаи ниҳоӣ.
Вокуниш ба '429': эҳтиром 'Retry-After', ҷараёни троллейбус; барои маҳдудкунии дарозмуддат - таназзул (фиристодани танҳо намудҳои рӯйдодҳои муҳим).

9) Мӯҳлати обуна

Сабти ном/Санҷиш: POST endpoint → даъват/вокуниш ё тасдиқи берун аз банд.
Иҷора (ихтиёрӣ): имзо то 'дуруст _ ба' эътибор дорад; тамдид - возеҳ.
Гардиши махфӣ: 'current _ secret', 'next _ secret' s 'switch _ at'.
Пинги санҷишӣ: як чорабинии сунъӣ барои санҷиши масир пеш аз фурӯзон кардани мавзӯъҳои асосӣ.
Намунаҳои саломатӣ: санҷиши даврии HEAD/GET бо таъхир ва профили TLS.

10) Эволютсияи схемаҳо (версияҳои рӯйдодҳо)

Навъи таҳрири ҳодиса: 'пардохт. ваколатдор шудааст. v1 '→'... v2 '.
Эволютсия - иловагиҳо (майдонҳои нав → версияҳои MINOR API), шикастани → навъи нав.
Феҳристи схема (JSON-Schema/Avro/Protobuf) + санҷиши худкор пеш аз пешниҳод.
Сарлавҳаи 'X-Event-Type' ва 'Schema _ version' дар бадан ҳарду талаб карда мешаванд.

11) Мушоҳида ва SLO

• 'deliveries _ total', '2xx/4xx/5xx _ rate', 'timeout _ rate', 'signature _ fail _ rate'.
• 'attempts _ avg', 'p50/p95/p99 _ delivery _ latency _ ms' (нашр ба 2xx).
• 'dedup _ rate', 'out _ of _ order _ rate', 'dlq _ rate', 'redrive _ success _ rate'.
• 'queue _ depth', 'қадимтарин _ in _ queue _ ms', 'drottle _ events'.

• Ҳиссаи таҳвилҳо ≤ 60 с (с95) - 99. 5% барои рӯйдодҳои интиқодӣ.
• DLQ ≤ 0. 1% дар 24 соат
• Хатои имзо ≤ 0. 05%.

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

12) Алгоритми истинодҳои ирсолкунанда

1. Навиштани ҳодиса ба баромади транзаксионӣ.
2. Муайян кардани partition_key ва seq; навбат.
3. Коргар калидро мегирад, дархост мекунад, аломатҳо мегузорад, бо танаффус мефиристад (пайваст/хонед).
4. Бо '2xx' - ҳамчун расонидашуда эътироф кунед, таъхир ва нуқтаи гузаришро ислоҳ кунед.
5. Бо '429/5xx/timeout' - ақибнишинӣ тибқи сиёсат.
6. Бо TTL → DLQ ва ҳушдор.

13) Протсессори истинод (қабулкунанда)

1. Дархостро қабул кунед, TLS/proto-ро санҷед.
2. Тасдиқи имзо ва равзанаи вақт.
3. Fast ACK 2xx (пас аз навиштани синхронӣ ба паёмдони маҳаллӣ/навбат).
4. Коргари асинхронӣ 'паёмдони' -ро мехонад, 'event _ id' (бобои) -ро месанҷад, дар ҳолати зарурӣ фармоишҳои 'seq' inside 'partition _ key' -ро месанҷад.
5. Эффектҳоро иҷро мекунад, барои мусолиҳа "нуқтаи назоратӣ/seq" менависад.
6. Дар мавриди хатогӣ - бозомӯзии маҳаллӣ; вазифаҳои "заҳролуд" → DLQ маҳаллӣ бо огоҳӣ.

14) оштӣ (ҳалқаи ҳавз)

• 'GET/чорабиниҳо? partition_key=...&after_seq=...&limit=...' - ба ҳама пазмоншуда.
• Нуқтаи гузаргоҳи токен: 'баъд аз = ношаффоф _ токен' ба ҷои seq.
• Бозсозии Idempotent: ҳамон 'event _ id', ҳамон имзо дар 't' -и нав.

15) Сарлавҳаҳо ва рамзҳои муфид

2xx - қабул карда шуд (ҳатто агар коркарди тиҷорат дертар бошад).
410 Gone - нуқтаи ниҳоӣ пӯшида аст (ирсолкунанда таҳвилро қатъ мекунад ва обунаро ҳамчун "бойгонӣ" қайд мекунад).
409/423 - масдудкунии муваққатии манбаъ → бозпас оқилона аст.
429 - хеле зуд § дроссель ва бозгашт.
400/401/403/404 - хатои конфигуратсия; retrai-ро боздоред, чиптаро кушоед.

16) Бисёр иҷорагир ва минтақаҳо

Навбатҳо ва маҳдудиятҳои инфиродӣ барои як иҷорагир/нуқтаи ниҳоӣ.
Ҷойгиркунии маълумот: фиристодани маълумот аз минтақа; сарлавҳаҳои ниҳоӣ 'X-Tenant', 'X-Region'.
Ҷудокунии нобарориҳо: афтодани як муштарӣ ба боқимонда (ҳавзҳои алоҳида) таъсир намерасонад.

17) Санҷиш

Санҷишҳои шартномавӣ: намунаҳои собитшудаи мақомот/имзоҳо, санҷиши тасдиқкунӣ.
Хаос: тарки/нусхабардорӣ, фармоиши омехта, таъхири шабака, хатогиҳои 'RST', 'TLS'.
Сарборӣ: тӯфони шадид, андозагирии p95/p99.
Амният: зидди такрорӣ, мӯҳлати кӯҳна, сирри нодуруст, гардиш.
DR/Replay: Интиқоли оммавӣ аз DLQ дар мавқеи ҷудогона.

18) Китобҳои бозӣ (китобчаҳо)

1. Афзоиши 'signature _ fail _ rate'

Санҷиши гардиши соат, гузаштани "таҳаммулпазирӣ", гардиши асрори; муваққатан фаъол кардани "сирри дугона".

2. Навбат пир шуда истодааст ('қадимтарин _ in _ queue _ ms')

Коргаронро зиёд кунед, афзалияти мавзӯъҳои муҳимро фароҳам оваред, басомади намудҳои "ғавғо" -ро муваққатан кам кунед.

3. Тӯфони '429' дар муштарӣ

Даргиронидани ҳаракат ва таваққуф дар байни кӯшишҳо; тағир додани намудҳои ҳодисаҳои камтар интиқодӣ.

4. Массаи '5xx'

Кушодани схема барои нуқтаи мушаххас, гузариш ба таъхир ва партия; сигнал ба муштарӣ.

5. Populate DLQ

Нашри ғайримуқаррариро қатъ кунед, имкон диҳед, ки гурӯҳро бо RPS-и паст интиқол диҳед, ба соҳибони обуна огоҳӣ диҳед.

19) Хатогиҳои маъмулӣ

Коркарди вазнини синхронӣ ба вокуниши 2xx → бозсозӣ ва нусхабардорӣ.
Имзои равзанаи бадан/вақт § иваз/такрори осебпазирӣ нест.
Набудани 'event _ id' ва 'inbox' → наметавонад idempotent бошад.
Кӯшиши "тартиботи ҷаҳонӣ" → қуфлҳои навбати абадӣ.
Ақибнишинӣ бе ҷиттер/маҳдудиятҳо → шиддатёбии ҳодисаҳо (галаи раъд).
Ҳавзи ягонаи умумӣ барои ҳамаи муштариён → "ғавғо" ҳамаро мегузорад.

20) Рӯйхати санҷиши пеш аз фурӯш

• Шартнома: 'event _ id', 'partition _ key', 'seq', 'event _ type. vN ', имзои HMAC ва мӯҳлатҳои вақт.
• Ирсолкунанда: outbox, serialization by key, бозгашт бо backoff + jitter, TTL, DLQ ва redrive.
• Қабулкунанда: зуд ба паёмдони + 2xx нависед; табобати idempotent; DLQ маҳаллӣ.
• Амният: TLS, имзоҳо, зидди такрорӣ, дугона-махфӣ, гардиш.
• Квотаҳо/маҳдудиятҳо: навбати одилона ба як иҷорагир/нуқтаи ниҳоӣ, эҳтиром 'Retry-After'.
• API ва нуқтаҳои гузаргоҳро барқарор кунед; ҳуҷҷатгузорӣ барои муштариён.
• Мушоҳида: p95/threads/errors/DLQ, пайгирӣ ба 'event _ id'.
• Сиёсати таҳаввулоти рӯйдодҳо ва нақшаи эволютсия.
• Китобҳои бозӣ дар бораи ҳодисаҳо ва тугмаи ҷаҳонии таваққуф/оббозӣ.

Хулоса

Вебхукҳои боэътимод як протокол дар болои HTTP мебошанд, на танҳо "POST бо JSON. "Шартномаи возеҳ (ID, калиди фармоиш, имзо), номутобиқатӣ, бозпас бо ҷиттер, навбати одилона ва дафтарҳои хуби дебугӣ беҳтарин ҳолатро ба механизми пешгӯишаванда ва ченшаванда табдил медиҳанд. Ҳадди аққал як маротиба + фармоиши калидӣ + оштӣ кунед ва система оромона аз шабака наҷот ёбад, қуллаҳо ва хатогиҳои инсонро бор кунад.