Webhooks: такрорӣ ва эътироф

1) Модели асосии таҳвил

Ақаллан як маротиба (пешфарз) - Чорабинӣ ≥ 1 маротиба расонида мешавад. Кафолатҳои маҳз як маротиба тавассути idempotency қабулкунанда ба даст оварда мешаванд.
Эътироф (ACK): танҳо ҳама гуна 2xx (одатан 200/204) аз қабулкунанда маънои муваффақиятро дорад. Ҳама чизи дигар ҳамчун нокомӣ шарҳ дода мешавад ва ба такрор оварда мерасонад.
ACK-и зуд: Пас аз ҷойгиркунии ҳодиса дар навбати худ, на пас аз коркарди пурраи тиҷорат, ба 2xx ҷавоб диҳед.

2) Формати чорабинӣ ва сарлавҳаҳои ҳатмӣ

Сарборӣ (мисол)

json
{
"id": "evt_01HXYZ",
"type": "order. created",
"occurred_at": "2025-11-03T18:10:12Z",
"sequence": 128374,
"source": "orders",
"data": { "order_id": "o_123", "amount": "49. 90", "currency": "EUR" },
"schema_version": 1
}

Сарлавҳаҳои фиристанда

'X-Webhook-Id: evt_01HXYZ' - ID ID-и нодир (истифода барои deduplication).
'X-Webhook-Seq: 128374' - пайдарпаии якхела (аз рӯи обуна/мавзӯъ).
'Имзои X: sha256 = <base64 (hmac_sha256 (бадан, махфӣ)>' - HMAC-подпись.
'X-Retry: 0,1,2... 'рақами санҷиш аст.
'X-Webhook-Version: 1' - таҳрири шартнома.
(ихтиёрӣ) 'Traceparent' - таносуби пайгирӣ.

Ҷавоб аз қабулкунанда

2xx - бомуваффақият қабул карда шуд (такрори минбаъда барои "ин" вуҷуд надорад).
410 Gone - нуқтаи ниҳоӣ нест карда шудааст/ғайрифаъол → ирсолкунанда дубора қатъ мекунад ва обунаро ғайрифаъол мекунад.
429/5xx/timeout - ирсолкунанда тибқи сиёсати бозпас такрор мешавад.

3) Сиёсати такрорӣ

Нардбони бозгашт тавсия дода мешавад (+ jitter)

'1s, 3s, 10s, 30s, 2m, 10m, 30m, 2h, 6h, 24h' (таваққуф пас аз маҳдудият, масалан 48-72 соат).

• Бозгашти экспоненсиалӣ + jitter тасодуфӣ (± 20-30%) барои пешгирӣ кардани "таъсири галаи".
• Кворуми хатогиҳо барои хатогиҳои муваққатӣ (масалан, такрори 5xx ё вақти шабака).
• Эҳтиром 429: ҳадди аққали 'min (Сарлавҳаи Retry-After, тирезаи навбатӣ)'.

Вақт ва андоза

Вақти пайвастшавӣ ≤ 3-5 сония; вақти умумии посух ≤ 10 сония

Андозаи бадан тибқи шартнома (масалан, ≤ 256 КБ), вагарна 413 → мантиқи "chunking" ё "URL-ро кашед".

4) Idempotency ва deduplication

Барномаи Idempotent: коркарди такрори ҳамон 'id' бояд ҳамон натиҷаро баргардонад ва ҳолати дигарро тағир надиҳад.
Нигоҳдории Dedup дар тарафи қабулкунанда: мағозаи '(X-Webhook-Id, processed_at, checksum)' бо тирезаҳои TTL ≥ retray (24-72 соат).
Калиди таркибӣ: агар якчанд мавзӯъ → '(subscription_id, event_id)'.

5) Фармоиш ва "эффектҳои якбора"

• Қисм аз рӯи калид: ҳамон маҷмӯи мантиқӣ (масалан, 'order _ id') ҳамеша дар як "канал" -и таҳвил аст.
• Пайдарпаӣ: Ҳодисаҳоро бо 'X-Webhook-Seq' -и кӯҳна рад кунед ва онҳоро дар "таваққуфгоҳ" пеш аз расидани шахсони гумшуда гузоред.

• сабти амалиётҳои татбиқшаванда (шакли қуттии/паёмдони қуттӣ),
• upsert transaction by 'event _ id' дар пойгоҳи додаҳо,
• sagas/ҷуброн барои равандҳои мураккаб.

6) Ҳалли хатогӣ аз рӯи рамзҳои ҳолат (Ҷадвал)

7) Амнияти канал

Имзои HMAC ҳар як паём; дар қабулкунак бо "равзанаи вақт" санҷед (ҳамлаҳои митм ва такрорӣ).
MTLS барои доменҳои ҳассос (LCC/пардохтҳо).
Рӯйхати IP allowlist суроғаҳои баромад, TLS 1. 2 +, HSTS.
Кам кардани PII: маълумоти шахсии нолозимро нафиристед; дар журналҳо пинҳон кунед.
Гардиши асрори: ду калиди дуруст (фаъол/оянда) ва сарлавҳаи 'X-Key-Id' барои нишон додани калиди ҷорӣ.

8) Навбатҳо, DLQ ва Такрори

Ҳодисаҳо бояд ба навбати баромад/сабти ном дар тарафи ирсолкунанда навишта шаванд (барои такрори боэътимод).
Агар ҳадди аксари бозпардохтҳо зиёд бошанд, ҳодиса бо DLQ (Dead Letter Queue) меравад.
Такрори API (барои қабулкунанда/оператор): дубора аз ҷониби 'id '/диапазони вақт/мавзӯъ, бо маҳдудияти RPS ва имзо/иҷозати иловагӣ.

POST /v1/webhooks/replay
{ "subscription_id": "sub_123", "from": "2025-11-03T00:00:00Z", "to": "2025-11-03T12:00:00Z" }
→ 202 Accepted

9) Шартнома ва версия

Нусхаи ҳодиса (майдони 'schema _ version') ва нақлиёт ('X-Webhook-Version').
Майдонҳоро танҳо ҳамчун ихтиёрӣ илова кунед; оид ба несткунӣ - муҳоҷирати ночиз ва давраи гузариш (дугона-навиштан).
Намудҳои рӯйдодҳои ҳуҷҷатӣ, намунаҳо, схемаҳо (JSON Schemas), рамзҳои хато.

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

• 'delivery _ success _ rate' (2xx/ҳама кӯшишҳо), 'first _ read _ success _ rate'
• 'reties _ total', 'max _ retry _ age _ seconds', 'dlq _ count'
• 'latency _ p50/p95' (occurred_at → ack_received_at)

• 'ak _ latency' (гирифтани § 2xx), 'коркард _ latency' (enqueue → анҷом дода мешавад)
• 'duplicates _ total', 'беэътибор _ signature _ total', 'out _ of _ order _ total'

99. 9% ҳодисаҳо аввалин ACK ≤ 60 сония (28d) мегиранд.

• DLQ ≤ 0. 1% аз шумораи умумӣ; Такрори DLQ ≤ 24 соат.

11) Танаффуси вақт ва шабака

Истифодаи UTC дар майдонҳои вақт; ҳамоҳангсозии NTP.
Фиристодани 'hollow _ at' ва ислоҳ кардани 'таслим _ at' барои хондани ақиб.
Бо танаффусҳои тӯлонӣ, шабака/нуқтаи ниҳоӣ → дар навбат ҷамъ шуда, афзоишро маҳдуд мекунад (ақибнишинӣ + квотаҳо).

12) Маҳдудиятҳо ва гигиенаи тавсияшуда

RPS барои як обуна (масалан, 50 RPS, таркиш 100) + мувофиқат (масалан, 10).
Макс. бадан: 64-256 КБ; барои бештар - "огоҳӣ + URL" ва зеркашии имзо.
Номҳои ҳодиса дар 'мор. парванда 'ё' нуқта. навъи '(' фармоиш. офаридааст ').
Idempotency қатъии амалиёти навиштани қабулкунанда.

13) Намунаҳо: Фиристанда ва қабулкунанда

13. 1 Фиристанда (псевдокод)

python def send_event(event, attempt=0):
body = json. dumps(event)
sig = hmac_sha256_base64(body, secret)
headers = {
"X-Webhook-Id": event["id"],
"X-Webhook-Seq": str(event["sequence"]),
"X-Retry": str(attempt),
"X-Signature": f"sha256={sig}",
"Content-Type": "application/json"
}
res = http. post(endpoint, body, headers, timeout=10)
if 200 <= res. status < 300:
mark_delivered(event["id"])
elif res. status == 410:
deactivate_subscription()
else:
schedule_retry(event, attempt+1) # backoff + jitter, respect 429 Retry-After

13. 2 Қабулкунанда (псевдокод)

python
@app. post("/webhooks")
def handle():
body  = request. data headers = request. headers assert verify_hmac(body, headers["X-Signature"], secret)
evt_id = headers["X-Webhook-Id"]
if dedup_store. exists(evt_id):
return, "" 204 enqueue_for_processing (body) # fast path. dedup_store put(evt_id, ttl=723600)
return, "" 202 # or 204

14) Таҷрибаҳои озмоишӣ ва бетартибӣ

Ҳолатҳои манфӣ: имзои беэътибор, 429/5xx, вақти корӣ, 410, бори калон.
Рафтор: фармоиш, нусхабардорӣ, таъхири 1-10 дақиқа, 24 соат танаффус.
Сарборӣ: дарида 10 ×; бознишастагӣ ва истодагарии DLQ-ро санҷед.
Шартномаҳо: Схемаи JSON, сарлавҳаҳои ҳатмӣ, намудҳои устувори рӯйдодҳо.

15) Рӯйхати назорати амалисозӣ

• 2xx = ACK, ва бозгашти зуд пас аз дархост
• Бозгашти экспоненсиалӣ + ҷиттер, эҳтиром 'Retry-After'
• Идентификатори қабулкунанда ва X-Webhook-Id (TTL ≥ Retray)
• Имзоҳои HMAC, гардиши махфӣ, ихтиёрии m: TLS
• DLQ + Такрори API, Мониторинг ва Огоҳиҳо
• Маҳдудиятҳо: Вақтсанҷӣ, RPS, Андозаи бадан
• Фармоиш: қисм аз рӯи калид ё 'пайдарпаӣ' + "таваққуфгоҳ"
• Ҳуҷҷатгузорӣ: схемаҳо, намунаҳо, рамзҳои хато, версияҳо
• Санҷишҳои бетартибӣ: таъхирҳо, нусхабардорӣ, шикасти шабака, такрори тӯлонӣ

16) Мини-FAQ

Оё ба ман ҳамеша лозим аст, ки ба 200 ҷавоб диҳам?
Ҳар гуна 2xx ҳамчун муваффақият ҳисобида мешавад. 202/204 таҷрибаи муқаррарӣ барои "қабул шудан ба навбат" мебошад.

Оё бозсозӣ метавонад қатъ карда шавад?
Бале, 410 посух ва/ё тавассути консол/API ирсолкунанда (обуна).

Дар бораи бори калон чӣ гуфтан мумкин аст?
"Огоҳӣ + URL-и бехатар" -ро фиристед, дархости зеркаширо имзо кунед ва TTL насб кунед.

Тартибро чӣ гуна бояд таъмин кард?
Қисмбандӣ аз рӯи калид + 'пайдарпаӣ'; дар ҳолати ихтилоф - "таваққуфгоҳ" ва такрорӣ.

Ҷамъ

Вебхукҳои боэътимод семантикаи дақиқи ACK (2xx), такрори оқилона бо бозгашт + ҷиттер, idempotence қатъӣ ва deduplication, амнияти босалоҳият (HMAC/MTLS), навбатҳо + DLQ + такрорӣ ва мушоҳидаҳои шаффоф мебошанд. Шартномаро ислоҳ кунед, маҳдудиятҳо ва ченакҳоро ворид кунед, сенарияҳои бетартибиҳоро мунтазам иҷро кунед - ва ҳамгироии шумо ҳангоми нокомии аввал "рехтан" -ро қатъ мекунад.