Webhooks և իրադարձությունների գաղափարախոսություն

TL; DR

Լավ Webhuk-ը ստորագրված է (HMAC/mTRK), որը ամփոփված և գաղափարական իրադարձություն է, որը առաքվում է at-leport-once մոդելի միջոցով էքսպոնենցիալ backoff-ի և ստացողի հետ։ Համաձայնեք ծրարի մասին («event _ id», «type», «version», «attempt», «signature»), ժամանակի պատուհանը (385 րոպե), պատասխանների կոդերը, retraces, DLQ և endpointe կարգավիճակը։

1) Դերերը և առաքման մոդելը

Ուղարկողը (դուք/պրովայդերը) ձևավորում է իրադարձություն, ստորագրում, փորձում է հասցնել մինչև 2xx x-ը, կտրում է 3xx/4xx/5xx-ը (բացի ակնհայտ «մի վերցրու»), առաջնորդում է DLQ-ը, տալիս է replay API-ը։

Ստացողը (գործընկեր/ձեր ծառայություն), ստուգում է ստորագրությունը/ժամանակավոր պատուհանը, անում է dedup և idempotent, պատասխանում է ճիշտ կոդին, տալիս է/status և/ack replay 'event _ id "։

Երաշխիքներ ՝ at-leport-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» -ը նախկինում չի մշակվել (dedup)

«X-Signature» -ը համընկնում է (թայմ-անվտանգ համեմատությամբ)

3. 2 Դոպ. միջոցներ

MTIM-ը բարձր բարեսիրտ Webhuks-ի համար։

IP/ASN allow-list.

DPoP (որոշ) sender-constrained-ի համար, եթե webhuk-ը հակադարձ զանգեր է առաջացնում։

4) Idempotenty և deduplication

4. 1 Idempotenty իրադարձություն

Նույն «event _ id» -ի հետ իրադարձությունը չպետք է փոխի վիճակը։ Ստացողը

պահպանում է «event _ id» ide կեշում (KV/Redis/BD) TTL-ի վրա 24-72 ժամ;

պահպանում է վերամշակման արդյունքը (հաջողությունը/սխալը, արտեֆակտները) 'վերադարձնելու համար։

4. 2 Թիմերի Idempotention (հակառակ զանգեր)

Եթե վեբհուկը ստիպում է հաճախորդին ծեծել API-ը (օրինակ ՝ «հաստատել payout»), օգտագործեք «Idempotency-Key» -ը այդ REST-մարտահրավերի վրա, պահեք արդյունքը մրցույթի կողմում (exactly-once)։

KV մոդելը (նվազագույն)


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

5) Retrai և backoff

Առաջարկվող գրաֆիկը (էքսպոնենցիալ ջիթերի հետ)

'5s, 15s, 30s, 1m, 2m, 5m, 10m, 10m, 30m, 1h, 3h, 6h, 12h, 42h "(հետո ամեն օր մինչև N օր)

Կոդերի լուծումները

2xx-ը հաջողությունն է, դադարեցնել ռետրոյները։

4xx:

«400/401/404/404/422» - մենք չենք կտրում, եթե ստորագրությունը/ձևաչափը (հաճախորդի սխալ)։
"429" - Retry-After "կամ backoff։
5x/ցանցը retraim է։

Ուղարկողի վերնագրերը ՝ «User-Agent», «X-Webhook-Server», «X-Attempt»։

6) Վերամշակում ստացողի կողքին

Pissdopipline

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» -ը '«ww.ru» -ի համար։

Երկար ճամբարների/ծածկագրերի համար ավելացրեք/replay ուղարկողի և/resync-ից ստացողի մոտ (ստանալ սարքավորումներ և հանգստավայրեր ժամանակի/ID)։

8) Կարգավիճակ, replay և DLQ

8. 1 Ուղարկողի էնդպոինտները

«POST/webhooks/replay» - ըստ «event _ id» ցուցակի կամ ժամանակի պատուհանի։

«GET/webhooks/events/: id» - ցույց տալ սկզբնական փաթեթը և փորձերի պատմությունը։

DLQ: «մեռած» իրադարձությունները (սպառված է ռետրերի սահմանափակում) կատարվում են առանձին պահեստ, ալտերտեր։

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

Մետրիկները (ուղարկողը)

wwww.ivery p50/p95, sucess rate, retray/իրադարձություն, drop-rate DLQ, 42xx/4xx/5xx x, ձգման պատուհանը մինչև 2xx։

Մետրիկի (ստացողը)

verify fail rate (ստորագրություն/ժամանակ), dup-rate, latency handler p95, 5xx։

SLO կենտրոններ

Առաքում ՝ 3699։ Իրադարձությունների 9 տոկոսը ստանում են 2xx <3 c p95 (առաջին հաջողակ փորձից հետո)։

Cryptoproverka: Ստորագրության վալիդացիան 2-5 ms p95 է։

Dedup: 0 կրկնվող էֆեկտներ (exactly-once procope տիրույթի մակարդակում)։

11) Տվյալների անվտանգությունը և գաղտնիությունը

Մի փոխանցեք PAN/PII-ը վեբհուկի մարմնում։ օգտագործեք ցուցիչներ և հաջորդ պոմպը հեղինակային API-ի մանրամասների հետևում։

Քողարկեք զգայուն դաշտերը լոգարաններում։ պահեք իրադարձությունների մարմինները միայն TTL-ի հետ։

Ծածկագրեք DLQ և repley։

12) Տարբերակումը և համատեղելիությունը

Տարբերակը 'version' (ծրար) և ճանապարհին '։

Նոր դաշտերը որոշակիորեն են։ հեռացումը միայն «Sunset» ժամանակահատվածից հետո է։

Փաստաթղթավորեք փոփոխությունները machine-readable changelog-ում (ավտոպրովիզացիայի համար)։

13) Թեստ-քեյսները (UAT chek թերթ)

Նույն «event _ id» - ի կրկնվող առաքումը մեկ ազդեցություն և «200» կրկնօրինակներ։
Ստորագրություն ՝ ճիշտ բանալին, սխալ բանալին, հին բանալին (ռոտացիան), «X-Timestamp» -ը պատուհանից դուրս։
Backoff: Ստացողը տալիս է «429's 'Retry-After» -ը ճիշտ դադար։
Կարգը 'իրադարձություններ «... processed 's գալիս է ավելի շուտ»... created 's ճիշտ մշակումը/սպասումը։
BD-ի ձախողումը էֆեկտի և «mark _ seen» -ի միջև ատոմականության/կրկնապատկիչի միջև։
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) Հաճախակի սխալներ

Դեդուպա չկա։ Կրկնվող էֆեկտներ (կրկնակի refands/peiauta)։

Ստորագրությունը առանց timstampa/պատուհանի հաստատվում է replay խոցելիությունը։

Մեկ HMAC գաղտնիքը բոլոր գործընկերների վրա։

«200» -ի պատասխանները մինչև արդյունքի ամրագրումը բացատրում են իրադարձությունների կորուստը քրեշի ժամանակ։

Անվտանգության մանրամասների «լվացումը» պատասխանների/լոգայի մեջ։

DLQ/repley-ի բացակայությունը անլուծելի է։

16) Ներդրման լրտեսը

Անվտանգություն: HMAC v1 + «X-Timestamp» + «X-Event-Id», պատուհանը 355 րոպե; MTIM/IP allow-liste-ը։

Առաքում ՝ at-leport-once, backoff ջիթթերի, «Retry-After», DLQ + replay API-ի հետ։

Конверт: `event_id`, `type`, `version`, `ts`, `attempt`, `data`.

Idempotention: KV-kes 24-72 ժամ, էֆեկտի ատոմային ամրագրումը + «mark _ seen»։

Դիտարկումը 'առաքման, ստորագրության, կրկնօրինակների չափումներ։ ուղու «trace _ id»։

Մոսկվան 'տարբերակ, պատասխաններ, օրինակներ, UAT-chek-թերթ։

Ռեզյումե

Կայուն webhuks կառուցվում են երեք կետերում 'ստորագրված ծրար, at-leport-once առաքում և idempotent վերամշակում։ Ֆորմալիզացրեք պայմանագիրը, միացրեք HMAC/mTRK-ը և ժամանակի պատուհանը, իրականացրեք + DLQ և reple-ները, պահեք idempotent կոդերը և արձանագրեք ատոմային էֆեկտները։ Այդ ժամանակ իրադարձությունները մնում են հուսալի նույնիսկ ցանցի ձախողումների, բեռի պիկի և հազվադեպ «ճակատագրի կրկնօրինակների» դեպքում։