Webhooks жана иш-чаралардын ыктымалдыгы

TL; DR

Жакшы вебхук - бул кол коюлган (HMAC/mTLS), экспоненциалдуу backoff жана алуучудан дедупликация менен ат-least-once модели боюнча жеткирилүүчү жыйынтыктоочу жана идемпотенттик окуя. Конверт ('event _ id', 'type', 'ts', 'version', 'attempt', 'signature'), убакыт терезеси (≤ 5 мин), жооп коддору, ретрайлер, DLQ жана статус-пункту жөнүндө макулдашуу.

1) Ролдору жана жеткирүү модели

Жөнөтүүчү (сиз/провайдер): окуяны түзөт, кол коет, 2xx чейин жеткирүүгө аракет кылат, 3xx/4xx/5xx боюнча ретраит (ачык "кабыл албагыла" дегенден тышкары), DLQ жүргүзөт, кайра АПИ берет.
Алуучу (өнөктөш/сиздин кызмат): кол тамганы/убактылуу терезени текшерет, дедуп жана демпотенттик иштетүүнү жасайт, туура код менен жооп берет ,/status жана/ack replay 'event _ id' менен камсыз кылат.

Кепилдиктер: at-least-once. Алуучу дубликаттарды иштеп чыгууну жана тартипти өзгөртүүнү билиши керек.

2) Конверт окуя (envelope)

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', 'attempt'.
Эволюция эрежелери: талааларды кошуу; түрүн алып салуу/өзгөртүү - жаңы 'version' менен гана.

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(now − `X-Timestamp`) ≤ 300s
• 'X-Event-Id' мурда иштелип чыккан эмес (дедуп)
• 'X-Signature' дал келет (тайм-коопсуз салыштыруу менен)

3. 2 кошумча. чаралар

mTLS жогорку сезгич Webhook үчүн.
IP/ASN allow-list.
DPoP (кошумча) үчүн sender-constrained, эгерде вебхук артка чалууларды демилгелесе.

4) Демпотенттүүлүк жана дедупликация

4. 1 Окуялардын окшоштугу

• TTL ≥ 24-72 саат боюнча Dampotent адам (KV/Redis/DD) 'event _ id' сактайт;
• кайра кайтаруу үчүн иштетүү натыйжасын (ийгилик/ката, артефакттар) сактайт.

4. 2 Командалардын ыктымалдыгы (кайра чакыруулар)

Эгерде вебхук кардарды APIди тартып алууга мажбурласа (мисалы, "payout тастыктады"), ошол REST чалууда 'Idempotency-Key' колдонуңуз, натыйжаны кызматтын тарабында сактаңыз (exactly-once outcome).

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

5) Ретраи жана backoff

• '5s, 15s, 30s, 1m, 2m, 5m, 10m, 30m, 1h, 3h, 6h, 12h, 24h' (N күнгө чейин күн сайын)

• 2xx - ийгилик, retraia токтотуу.

• '400/ 401/403/404/422' - кол тамга/формат ок болсо, ретраим эмес (кардар ката).
• '429' - ретраим 'Retry-After' же backoff.
• 5хх/тармак - ретраим.

Жөнөтүүчүнүн аталыштары: 'User-Agent', 'X-Webhook-Producer', 'X-Attempt'.

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

Транзакциялуулук: "seen" белгиси ийгиликсиз болгондо кош иштетүүнү болтурбоо үчүн операциянын таасири менен атомдук түрдө коюлушу керек (же натыйжаны бекиткенден кийин).

7) Тартиптин жана снапшоттун кепилдиктери

Тартип кепилденбейт. 'ts' жана домендерди 'seq '/' version' менен 'data' колдонуңуз.
Узак лагдар/жоготуулар үчүн - жөнөтүүчүдөн/replay жана/resync алуучудан (убакыт/ID терезеси боюнча снапшот жана дельталарды алуу) кошуңуз.

8) Статус, replay жана DLQ

8. 1 Жөнөтүүчүнүн эндпоинттери

'POST/webhooks/replay' - 'event _ id' тизмеси же убакыт терезеси боюнча.
'GET/webhooks/events/: id' - баштапкы пакетин жана аракет тарыхын көрсөтүү.
DLQ: "өлүк" окуялар (Retray чеги түгөнгөн) → өзүнчө сактоо, алерталар.

8. 2 Алуучунун эндпоинттери

`GET /webhooks/status/:event_id` — `seen=true/false`, `processed_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, success rate, retry/окуя, drop-rate DLQ, share 2xx/4xx/5xx, 2xx чейин кечигүү терезе.

• verify fail rate (кол/убакыт), dup-rate, latency handler p95, 5xx.

• Жеткирүү: ≥ 99. окуялардын 9% 2xx <3 c p95 алат (биринчи ийгиликтүү аракеттен кийин).
• Крипто текшерүү: кол валидация ≤ 2-5 ms p95.
• Дедуп: 0 кайталануучу эффекттер (домен деңгээлинде exactly-once outcome).

11) Маалымат коопсуздугу жана купуялык

PAN/PIIди вебхук телосуна өткөрбөө; күбөлөндүрүлгөн API боюнча деталдарды аныктоо жана кийинки pull колдонуу.
Түйүндөрдөгү сезгич талааларды жашырыңыз; TTL менен, минималдуу гана окуялардын денесин сактоо.
DLQ жана реплика кампаларын шифрлөө.

12) Версия жана шайкештиги

'version' версиясы (конверт) жана жолдо: '/webhooks/v1/payments '.
Жаңы талаалар - кошумча; алып салуу - "Sunset" мезгилинен кийин гана.
machine-readable changelog өзгөртүүлөрдү документтештирүү (autoprection үчүн).

13) Сыноо учурлары (UAT чек тизмеси)

• Ошол эле 'event _ id' → бир таасир жана '200' кайталап жеткирүү.
• Кол тамга: туура ачкыч, туура эмес ачкыч, эски ачкыч (айлануу), 'X-Timestamp' терезенин сыртында.
• Backoff: алуучу берет '429' менен 'Retry-After' → туура тыныгуу.
• Тартиби: окуялар '... processed' мурда келет '... created' → туура иштетүү/күтүү.
• таасир жана 'mark _ seen' → атомдук/кайталоо ортосунда алуучунун DD ката.
• DLQ жана кол replay → ийгиликтүү жеткирүү.
• Массалык "бороон" (провайдер пакеттерди жөнөтөт) → жоготуусуз, лимиттер критикалык муунтпайт.

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) Көп каталар

Жок дедуп → кайталанма таасирлери (кош refand/пейауттар).
Таймштампсыз/терезесиз кол → replay үчүн алсыздык.
Бардык өнөктөштөр үчүн бир HMAC-жашыруун сактоо.
Жооптор '200' жыйынтыкты жазууга чейин → crash учурунда окуяларды жоготуу.
жооп/логиде коопсуздук бөлүктөрүн "жууп".
DLQ/репликанын жоктугу - инциденттер чечилбейт.

16) Шпаргалка киргизүү

Коопсуздук: HMAC v1 + 'X-Timestamp' + 'X-Event-Id', терезе ≤ 5 мин; mTLS/IP allow-list зарылчылыгы боюнча.
Конверт: `event_id`, `type`, `version`, `ts`, `attempt`, `data`.
Жеткирүү: at-least-once, jitter менен backoff, 'Retry-After', DLQ + replay API.
Демпотенттик: KV-кэш 24-72 саат, атомдук таасир бекитүү + 'mark _ seen'.
Байкоо: жеткирүү метрика, кол, дубликат; 'trace _ id'.
Документация: версия, жооп коддору, мисалдар, UAT чек тизмеси.

Резюме

Туруктуу Webhuke үч киттер боюнча курулган: кол коюлган конверт, at-least-once жеткирүү жана idempotent иштетүү. Келишимди формализациялоо, HMAC/mTLS жана убакыт терезесин күйгүзүү, ретраларды + DLQ жана репликаларды ишке ашыруу, демпотент белгилерин сактоо жана атомдук эффекттерди оңдоо. Андан кийин иш-чаралар да тармактын бузулушу, жүк чокулары жана сейрек кездешүүчү "тагдырдын дубликаттары" менен ишенимдүү бойдон калууда.