Webhooks ва idempotency ҳодиса

TL; ДР

Webhook хуб як имзошуда аст (HMAC/MTLS), чорабинии ҷамъбастшуда ва ғайримуқаррарӣ, ки дар модели ҳадди аққал як бор бо пуштибонии экспоненсиалӣ ва такрорӣ дар гиранда оварда шудааст. Дар лифофа ('event _ id', 'type', 'ts', 'версия', 'кӯшиш', 'имзо'), равзанаи вақт (≤ 5 дақиқа), рамзҳои ҷавоб, бозсозӣ, DLQ ва нуқтаи ниҳоӣ мувофиқат кунед.

1) Нақшҳо ва модели таҳвил

Фиристанда (шумо/провайдер): ҳодиса эҷод мекунад, аломатҳо мегузорад, кӯшиш мекунад, ки то 2xx расонад, дар 3xx/4xx/5xx бозгардад (ба истиснои возеҳи "қабул накунед"), DLQ, такрори API медиҳад.
Қабулкунанда (шарик/хидмати шумо): равзанаи имзо/вақтро тафтиш мекунад, коркарди dedup ва idempotent месозад, бо рамзи дуруст ҷавоб медиҳад, такрори/ҳолат ва/ackро тавассути '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 _ id', 'type', 'version', 'ts', 'кӯшиш' мебошанд.
Қоидаҳои эволютсия: илова кардани майдонҳо; намудҳои нест кардан/тағир додан - танҳо бо 'версияи' нав.

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') ≤ 300-ум
• 'X-Event-Id' not қаблан коркард шуда буд (dedup)
• 'X-Signature' matches (муқоисаи бехатар аз вақт)

3. 2 Тадбирҳои илова

MTLS барои веб-китобҳои ҳассос.
Рӯйхати иҷозати IP/ASN.
Агар DP webhook зангҳоро оғоз кунад, DP oP (ихтиёрӣ) барои ирсолкунанда маҳдуд аст.

4) Idempotency ва deduplication

4. 1 Idempotency ҳодиса

• 'event _ id' in cache idempotent (KV/Redis/DB) дар TTL ≥ 24-72 соат;
• натиҷаи коркард (муваффақият/хатогӣ, артефактҳо) -ро барои бозгашт нигоҳ медорад.

4. 2 Номутобиқатии фармон (зангҳо)

Агар webhook муштариро маҷбур кунад, ки API-ро кашад (масалан, "пардохтро тасдиқ кунед"), дар занги REST 'Idempotency-Key' -ро истифода баред, натиҷаро дар тарафи хидмат нигоҳ доред (маҳз як маротиба натиҷа).

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

5) Ретрай ва бозгашт

• '5s, 15s, 30s, 1 m, 2 m, 5 m, 10 m, 30 m, 1h, 1h, 3h, 6h, 12h, 24h' (пас ҳамарӯза то N рӯз)

• 2xx - муваффақият, бознишастагӣ.

• '400/ 401/403/404/422' - баргардонида намешавад, агар имзо/формат хуб бошад (хатои муштарӣ).
• '429' - бозгашт аз ҷониби 'Retry-After' ё бозгашт.
• 5xx/шабака - retrayim.

Сарлавҳаҳои ирсолкунанда: 'Корбар-Агент', 'X-Webhook-Productor', 'X-Кӯшиш'.

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' ва домени 'seq '/' версияро' дар 'маълумот' истифода баред.
Барои ақибмонӣ/талафоти дароз - илова/такрорӣ дар ирсолкунанда ва/resync дар қабулкунанда (гирифтани сурат ва дельтҳо дар вақти/тирезаи ID).

8) Ҳолат, такрорӣ ва DLQ

8. 1 Нуқтаи хотимавии фиристанда

'POST/webhooks/replay' - аз ҷониби 'event _ id' list ё аз ҷониби равзанаи вақт.
'GET/webhooks/events/: id' - бастаи манбаъ ва таърихи кӯшишҳоро нишон диҳед.
DLQ: ҳодисаҳои "мурда" (лимити бозгашт тамом шудааст) → нигоҳдории алоҳида, огоҳиҳо.

8. 2 Нуқтаҳои қабулкунанда

'GET/ webhooks/status/:event_id' -' дида мешавад = ҳақиқӣ/бардурӯғ ',' коркардшуда _ 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, сатҳи муваффақият, бозгашт/ҳодиса, DLQ-и тарки, мубодилаи 2xx/4xx/5xx, тирезаи таъхир то 2xx.

• меъёри нокомиро тафтиш кунед (имзо/вақт), dup-rate, handler latency p95, 5xx.

• Расонидан: ≥ 99. 9% ҳодисаҳо 2xx <3 c p95 мегиранд (пас аз кӯшиши аввалини муваффақ).
• Санҷиши криптографӣ: тасдиқи имзо ≤ 2-5 ms p95.
• Dedup: 0 эффектҳои такрорӣ (маҳз як маротиба натиҷа дар сатҳи домейн).

11) Амнияти маълумот ва махфият

PAN/PII-ро дар бадани webhook интиқол надиҳед; ID-ро истифода баред ва баъд тафсилотро бар зидди API-и ваколатдор гиред.
Майдонҳои ҳассосро дар гузоришҳо маска кунед; мақомоти ҳодисаро танҳо ҳадди аққал бо TTL нигоҳ доред.
Рамзгузории DLQ мағозаҳо ва такрорӣ.

12) Версия ва мутобиқат

Версия дар 'версия' (лифофа) ва дар транзит: '/webhooks/v1/payments '.
Майдонҳои нав ихтиёрӣ мебошанд; хориҷ кардан - танҳо пас аз давраи "ғуруби офтоб".
Ҳуҷҷатгузорӣ кардани тағйирот дар тағйири мошини хондашаванда (барои худкори чек).

13) Парвандаҳои санҷишӣ (рӯйхати назоратии UAT)

• Пешниҳоди якхелаи 'event _ id' → як таъсир ва '200' барои такрорӣ.
• Имзо: калиди дуруст, калиди нодуруст, калиди кӯҳна (гардиш), 'X-Timestamp' аз тиреза.
• Бозгашт: Қабулкунанда '429' with 'Retry-After' § таваққуфи дуруст медиҳад.
• Фармоиш: Ҳодисаҳо '... коркард 'биёед'... сохта шудааст '→ коркарди дуруст/интизорӣ.
• Нокомии пойгоҳи додаҳо дар қабулкунанда байни эффект ва 'mark _ seed' → atomicity/такрор.
• DLQ ва такрори дастӣ → расонидани бомуваффақият.
• Массаи "тӯфон" (провайдер бастаҳо мефиристад) → бе талафот, маҳдудиятҳо танқидӣ намедиҳанд.

14) порчаҳои мини

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) Хатогиҳои зуд-зуд

Не deduplication → эффектҳои такрорӣ (refands/пардохтҳои дукарата).
Имзо бе вақт/тиреза → осебпазирии такрорӣ.
Нигоҳ доштани як сирри HMAC ба ҳамаи шарикон.
Ҷавобҳо '200' пеш аз муайян кардани натиҷа → аз даст додани ҳодисаҳои садама.
Тафсилоти амниятро "шустушӯ" дар ҷавобҳо/гузоришҳо.
Набудани DLQ/такрорӣ - ҳодисаҳо ҳалнашавандаанд.

16) Варақаи фиреб

Амният: HMAC v1 + 'X-Timestamp' + 'X-Event-Id', тиреза ≤ 5 дақиқа; Агар лозим бошад, рӯйхати иҷозати M TLS/IP.
Konvert: 'event _ id', 'type', 'version', 'ts', 'кӯшиш', 'data'.
Таҳвил: ҳадди аққал як маротиба, бозгашт бо ҷиттер, 'Retry-After', DLQ + такрори API.
Идемпотенсия: KV-кэш 24-72 соат, мустаҳкамкунии атомии эффект + 'mark _ seed'.
Мушоҳида: расонидан, имзо кардан, ченакҳои такрорӣ; пайгирӣ _ ид.
Ҳуҷҷатгузорӣ: версия, рамзҳои вокуниш, намунаҳо, рӯйхати назоратии UAT.

Хулосаи дубора

Веб-дастгоҳҳои доимӣ дар се китҳо сохта шудаанд: лифофаи имзошуда, ҳадди аққал як бор расонидан ва коркарди idempotent. Шартномаро ба расмият дароред, HMAC/MTLS ва равзанаи вақтро фаъол созед, retrai + DLQ-ро иҷро кунед ва дубора нусхабардорӣ кунед, тамғакоғазҳои номатлубро нигоҳ доред ва эффектҳои атомиро сабт кунед. Он гоҳ ҳодисаҳо ҳатто бо шикасти шабака, қуллаҳои борбардор ва "нусхаҳои нодир" -и тақдир боэътимод боқӣ мемонанд.