Webhooks 'կրկնություն և քվիտացիա

1) Ռուսական առաքման մոդելը

At-leport-once (լռելյայն), իրադարձությունը կհանձնվի 241 անգամ։ Երաշխիքները ուղիղ մեկ անգամ հասնում են ընդունիչի համադրությանը։

Քվիտացիան (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 իրադարձություններ (օգտագործեք dedupliation համար)։

«X-Webhook-Seq: 128384» մոնոտոնային հաջորդականություն է (բաժանորդագրվելով/թեման)։

`X-Signature: sha256=<base64(hmac_sha256(body, secret))>` — HMAC-подпись.

«X-Retry: 0,1,2...» - փորձի համարը։

«X-Webhook-Version: 1» պայմանագրի տարբերակն է։

(oporation) «Traceparent» -ը հետքերի հարաբերությունն է։

Ստացողի պատասխանը

2xx-ը հաջողությամբ ընդունվում է (դրանից հետո կրկնիչները չեն լինի)։

410 Gone - endpoint հեռավոր/չարտոնված, ուղարկողը դադարում է կրկնությունները և ակտիվացնում է բաժանորդագրությունը։

429/5hh/timaut - ուղարկողը կրկնում է retrav քաղաքականությունը։

3) Խոհարարների քաղաքականությունը (retries)

Վերացված սանդուղք backoff (+ jitter)

«1s, 3s, 10s, 30s, 2m, 10m, 30m, 2h, 6h, 7h» (կանգնում ենք սահմանից հետո, օրինակ 48-72 ժամ)։

Կանոնները

Էքսպոնենցիալ backoff + պատահական jitter (2420-30%) խուսափելու համար «համ էֆեկտը»։

Քվորումը ձախողումների համար (օրինակ, խոհարար, եթե 5xx կամ ցանցային թայմաուտ)։

Resport 429: Տեղադրեք նվազագույն "min" (վերնագիր Retry-After, հաջորդ պատուհանը backoff) "։

Թայմաուտները և չափսերը

Timaut-ի միացությունները 3-5 վայրկյան; պատասխանը 10 վայրկյան է։

Մարմնի չափը պայմանագրով (օրինակ ՝ 256 KB), հակառակ դեպքում 413 հազար տրամաբանություն «chunking» կամ «pox URL»։

4) Idempotenty և deduplication

Idempotent կիրառումը 'նույն' id '-ի կրկնօրինակների մշակումը պետք է վերադարձնի նույն արդյունքը և չփոխի վիճակը։

Dedup-պահեստը ստացողի կողմում 'պահել "(X-Webhook-Id, processed _ at, noksum)' TTL-ից retrav պատուհանները (24-72 ժամ)։

Կոմպոզիցիոն բանալին 'եթե մի քանի տեղանուններ են «(wwww.scription _ id, event _ id)»։

5) Կարգը և «exactly-once էֆեկտները»

Երաշխավորել խիստ կարգը դժվար է բաշխված համակարգերում։ Օգտագործեք

Partronby key: նույն տրամաբանական բազմությունը (օրինակ ՝ «order _ id») միշտ մեկ «առաքման ալիքի» մեջ։

Sequence: շեղեք իրադարձությունները հին 'X-Webhook-Seq-ի հետ և դրանք տեղադրեք «parking lot» մինչև անհայտ կորածների գալը։

Exactly-once էֆեկտները հասնում են

օգտագործված վիրահատությունների ամսագիրը (wwww.box/inbox pattern),

Գործարքային ussport համաձայն 'event _ id' - ը BD-ում,

sagi/փոխհատուցում բարդ գործընթացների համար։

6) Սխալների լուծումը կոդերի կարգավիճակի վրա (108)

7) Ջրանցքի անվտանգությունը

HMAC ստորագրությունը յուրաքանչյուր հաղորդագրության; ստուգում «ժամանակի պատուհանից» (mitm և replay հարձակումներ)։

MTSA զգայուն վճարումների համար (KUS/վճարումներ)։

IP allowlist, TMS 1։ 2+, HSTS.

PII-նվազեցում. Մի ուղարկեք լրացուցիչ անձնական տվյալներ։ լույսերի մեջ քողարկեք։

Գաղտնիքների վերացումը 'երկու գործող բանալին (action/next) և «X-Key-Id» վերնագիրը, որպեսզի նշի ներկա։

8) Գծեր, DLQ և reple

Իրադարձությունները պետք է գրվեն արձակուրդային հերթում/ամսագիր ուղարկողի կողմից (հուսալի գրանցման համար)։

Երբ ավելանում է ռետրերի մաքսիմը, իրադարձությունը գնում է DLQ (Dead Letter Queue) պատճառով։

ReplAPI (ստացողի/օպերատորի համար) 'ժամանակի/թեմայի կրկնվող ուղարկումը, RPS սահմանափակումով և ավելացված ստորագրությամբ/հեղինակային։

Օրինակ Replay API (ուղարկողը)

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 ")։

Ավելացրեք դաշտերը միայն որպես օպորացիոնալ։ հեռացնելիս 'մինորական միգրացիա և անցումային շրջան (dance-write)։

Փաստաթղթավորեք իրադարձությունների տեսակները, օրինակները, սխեմաները (JSON Schema), սխալները։

10) Դիտարկումը և SLO-ն

Ուղարկողի հիմնական մետրերը

«wwww.ivery _ success _ rate» (2x/բոլոր փորձերը), «first _ attempt _ sucess _ rate _ rate»

`retries_total`, `max_retry_age_seconds`, `dlq_count`

`latency_p50/p95` (occurred_at → ack_received_at)

Ստացողի հիմնական մետրերը

`ack_latency` (receive → 2xx), `processing_latency` (enqueue → done)

`duplicates_total`, `invalid_signature_total`, `out_of_order_total`

SLO օրինակներ

99. Իրադարձությունների 9 տոկոսը ստանում են առաջին ACK 2460 վայրկյան (28d)։

DLQ ≤ 0. Ընդհանուր թվի 1 տոկոսը։ DLQ 3524 reple

11) Թայմինգը և ցանցի կոտրվածքները

Օգտագործեք UTC-ը ժամանակի սահմաններում։ համաժամեցեք NTP-ին։

Ուղարկեք "occurred _ at" և գրեք 'www.ivered _ at ", որպեսզի հաշվի լագը։

Երկար ընդմիջումներով ցանցը/endpoint-ը տեղադրեք հերթում, սահմանափակեք աճը (backpressure + քվոտա)։

12) Չարտոնված սահմանները և հիգիենան

RPS բաժանորդագրության վրա (օրինակ, 50 RPS, burst 100) + զուգահեռ (օրինակ, 10)։

Մաքս։ մարմինը '64-256 KB; ավելին համար '«notif.ru + URL» և ստորագրության համար։

Իրադարձությունների անունները 'www.ake։ com 'կամ' dot. type` (`order. created`).

Ընդունիչի խիստ գաղափարախոսությունը։

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, մեծ payload' a։

Վարքագծային 'out-of-order, կրկնօրինակներ, 1-10 րոպե ձգումներ, 24 ժամ ընդմիջում։

Բեռները 'burst 10 ռուբլիներ; backpressure և DLQ կայունությունը։

Պայմանագրեր ՝ JSON Schema, պարտադիր վերնագրեր, իրադարձությունների կայուն տեսակներ։

15) Ներդրման չեկի ցուցակ

• 2xx = ACK, արագ միացում enqueue-ից հետո
• Էքսպոնենցիալ backoff + jitter, հարգանք «Retry-After»
• Ստացողի և dedup 'X-Webhook-Id' (TTL retrai)
• HMAC ստորագրությունները, գաղտնիքների լուծարումը, optional mTRK-ը, optional mTRK-ը, optional mTLS-ը, optional mTLS-ը։
• DLQ + Replay API, ռուսական և ալտերտեր
• Սահմանափակումներ ՝ թայմաուտներ, RPS, մարմնի չափը
• Կարգը ՝ partronby key կամ 'sequence' + «parking lot»
• - Սխեմաներ, օրինակներ, սխալների կոդավորում, տարբերակներ
• Քաոս թեստեր 'ձգձգումներ, դուբլի, ցանցի մերժում, երկար replay

16) Mini-FAQ

Պե՞ տք է արդյոք միշտ պատասխանել 200։

Յուրաքանչյուր 2xx-ը հաշվարկվում է որպես հաջողություն։ 2019/204-ը նորմալ պրակտիկա է «հերթում» համար։

Կարո՞ ղ ենք դադարեցնել կրկնությունը։

Այո, պատասխանը 410 և/կամ վահանակի/API ուղարկողի միջոցով (անջատումը)։

Ինչպե՞ ս լինել մեծ payload 'ami

Ուղարկեք «ծանուցում + secure URL», ստորագրեք ներբեռնման և TTL-ի պահանջը։

Ինչպե՞ ս կարող ենք կարգուկանոն ապահովել։

Partition by key + `sequence`; երբ բաժանվելիս '«parking lot» և ընդմիջում։

Արդյունքը

Հուսալի webhuks - ACK (2xx), խելացի կրկնություններ backoff + jitter, խիստ գաղափարախոսություն և deduplication, գրագետ անվտանգություն (HMAC/mTRK), + DLQ + reple գծերը, և թափանցիկ դիտարկումը։ Ամրագրեք պայմանագիրը, մուտքագրեք սահմանաչափեր և չափումներ, պարբերաբար քաոս սցենարները, և ձեր արտադրանքները կդադարեն «դուրս գալ» առաջին ձախողումների ժամանակ։