Webhooks: გამეორება და ქვითარი

1) ძირითადი მიწოდების მოდელი

At-least-once (სტანდარტულად): ღონისძიება 1 ჯერ გადაეცემა. გარანტიები ზუსტად ერთხელ მიიღწევა მიმღების იდემპოტენტურობით.
ქვითარი (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 მოვლენაა (გამოიყენეთ დედაპლატაციისთვის).
'X-Webhook-Seq: 128374' - ერთფეროვანი თანმიმდევრობა (გამოწერის/თემის მიხედვით).
`X-Signature: sha256=<base64(hmac_sha256(body, secret))>` — HMAC-подпись.
'X-Retry: 0.1.2...' - მცდელობის ნომერი.
'X-Webhook-Version: 1' - ხელშეკრულების ვერსია.
(სურვილისამებრ) 'Traceparent' - მარშრუტების კორელაცია.

მიმღების პასუხი

2xx - წარმატებით მიიღეს (ამ 'id- ზე გამეორება აღარ იქნება).
410 Gone - დისტანციური/არააქტიური, გამგზავნი წყვეტს გამეორებას და ააქტიურებს გამოწერას.
429/5xx/Taimaut - გამგზავნი იმეორებს რეტრაის პოლიტიკას.

3) გამეორების პოლიტიკა (რეპეტიციები)

რეკომენდებული backoff კიბე (+ jitter)

'1s, 3s, 10s, 30s, 2 მ, 10 მ, 30 მ, 2h, 6h, 24h' (შეჩერებულია ლიმიტის შემდეგ, მაგალითად, 48-72 საათი).

• ექსპონენციალური backoff + შემთხვევითი jitter (± 20-30%) თავიდან ასაცილებლად „ნახირი ეფექტი“.
• შეცდომების კვორუმი დროებითი წარუმატებლობისთვის (მაგალითად, გამეორება, თუ 5xx ან ქსელის ტაიმუტი).
• Respect 429: დააყენეთ მინიმალური 'min (სათაური Retry-After, შემდეგი backoff ფანჯარა)'.

ტაიმაუტები და ზომები

ნაერთის ტაიმუტი 3-5 წამი; პასუხის მთლიანი ტაიმუტი 10 წამი.
სხეულის ზომა ხელშეკრულებით (მაგალითად, 256 KB), წინააღმდეგ შემთხვევაში 413 არის „chunking“ ან „pull URL“ ლოგიკა.

4) Idempotence და deduplication

იდემპოტენტური გამოყენება: იგივე 'id' გამეორებების დამუშავებამ უნდა დაუბრუნოს იგივე შედეგი და არ შეცვალოს მდგომარეობა.
დედაპლატის საცავი მიმღების მხარეს: შენახვა '(X-Webhook-ID, processed _ at, checksum)' s TTL - Retray ფანჯრები (24-72 საათი).
კომპოზიციური გასაღები: თუ რამდენიმე ტოპიკია '(subscription _ id, event _ id)'.

5) ბრძანება და „exactly-once ეფექტები“

• Partition by key: იგივე ლოგიკური ნაკრები (მაგალითად, 'order _ id') ყოველთვის მიწოდების ერთ „არხზე“.
• Sequence: გადახედეთ მოვლენებს ძველი „X-Webhook-Seq“ - ით და დააყენეთ ისინი „პარკინგის ლოტზე“, სანამ დაკარგული არ არის.

• გამოყენებული ოპერაციების ჟურნალი (outbox/inbox pattern),
• გარიგების გარიგება 'event _ id' BD- ში,
• საგები/ანაზღაურება რთული პროცესებისთვის.

6) შეცდომების გადაწყვეტა სტატუს კოდებზე (ცხრილი)

7) არხის უსაფრთხოება

თითოეული წერილის HMAC ხელმოწერა; შემოწმება მიღებაზე „დროის ფანჯრით“ (mitm და replay შეტევები).
mTLS მგრძნობიარე დომენებისთვის (KUS/გადახდები).
გამავალი მისამართების IP allowlist, TLS 1. 2+, HSTS.
PII შემცირება: არ გაგზავნოთ დამატებითი პერსონალური მონაცემები; შენიღბეთ ლოგებში.
საიდუმლოებების როტაცია: ორი აქტიური გასაღები (აქტივი/შემდეგი) და სათაური „X-Key-Id“ მიმდინარე მითითებისთვის.

8) რიგები, DLQ და ფრჩხილები

მოვლენები აუცილებლად იწერება შაბათ-კვირას/ჟურნალი გამგზავნის მხარეს (საიმედო რეპლიკისთვის).
თუ მაქსიმალური რეაგირება აღემატება, მოვლენა მიდის DLQ- ში (Dead Letter Queue) მიზეზით.
Replay 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 ').
დაამატეთ მინდვრები მხოლოდ როგორც სურვილისამებრ; მოცილებისას - უმცირესობის მიგრაცია და გარდამავალი პერიოდი (ორმაგი-write).
აღწერეთ მოვლენების ტიპები, მაგალითები, სქემები (JSON სქემა), შეცდომების კოდი.

10) დაკვირვება და SLO

• 'delivery _ success _ rate' (2xx/ყველა მცდელობა), 'first _ attempt _ attempt _ success _ 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`

99. მოვლენების 9% იღებს პირველ ACK 60 წამს (28d).

• 11) ტაიმინგი და ქსელის შესვენებები

გამოიყენეთ UTC დროის სფეროებში; სინქრონიზაცია NTP.
გაგზავნეთ 'occurred _ at' და ჩაწერეთ 'delivered _ at', რათა ლაგი ჩაითვალოს.
გრძელი ხარვეზებით, ქსელი/endpoint, დაგროვება რიგში, შეზღუდეთ ზრდა (backpressure + კვოტები).

12) რეკომენდებული ლიმიტები და ჰიგიენა

RPS გამოწერისთვის (მაგალითად, 50 RPS, burst 100) + პარალელიზმი (მაგალითად, 10).
მაქს. სხეული: 64-256 KB; უფრო მეტისთვის - „განცხადება + URL“ და ხელმოწერა გადმოტვირთვაზე.
Snake მოვლენების სახელები. case 'ან' dot. type` (`order. created`).
მიმღების write ოპერაციების მკაცრი idempotence.

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, დიდი პაილოდი.
ქცევითი: out-of-order, დუბლიკატები, შეფერხებები 1-10 წუთი, უფსკრული 24 საათის განმავლობაში.
დატვირთვა: burst 10 ×; შეამოწმეთ backpressure და DLQ სტაბილურობა.
კონტრაქტები: JSON Schema, სავალდებულო სათაურები, სტაბილური ტიპის მოვლენები.

15) განხორციელების სია

• 2xx = ACK და სწრაფი დაბრუნება enqueu- ს შემდეგ
• ექსპონენციალური backoff + jitter, პატივისცემა 'Retry-After'
• მიმღებისა და დედობის Idempotence 'X-Webhook-Id' (TTL retrai)
• HMAC ხელმოწერები, საიდუმლოებების როტაცია, optional mTLS
• DLQ + Replay API, მონიტორინგი და ალერტები
• შეზღუდვები: ტაიმაუტები, RPS, სხეულის ზომა
• შეკვეთა: წვეულება კეი ან 'sequence' + „parking lot“
• დოკუმენტაცია: სქემები, მაგალითები, შეცდომების კოდირება, ვერსიები
• ქაოსის ტესტები: შეფერხებები, დუბლები, ქსელის უკმარისობა, გახანგრძლივება

16) მინი-FAQ

ყოველთვის უნდა ვუპასუხოთ 200-ს?
ნებისმიერი 2xx ითვლება წარმატებად. 202/204 ნორმალური პრაქტიკაა „რიგში მიღებული“.

შესაძლებელია გამეორების შეჩერება?
დიახ, პასუხი 410 ან/და გამგზავნის კონსოლის/API- ს საშუალებით (გამოწერის გამორთვა).

როგორ მოვიქცეთ დიდ პაილოადთან?
გაგზავნეთ „შეტყობინება + secure URL“, ხელი მოაწერეთ მოთხოვნას ჩამოტვირთვა და დააინსტალირეთ TTL.

როგორ უნდა უზრუნველყოს წესრიგი?
Partition by key + `sequence`; განსხვავების დროს - „პარკინგი ლოტი“ და რეპლიკაცია.

შედეგი

საიმედო ვებჰუკები არის მკაფიო ACK (2xx) სემანტიკა, გონივრული გამეორება backoff + jitter- დან, მკაცრი idempotence და დედაპლიკაცია, კომპეტენტური უსაფრთხოება (HMAC/mTLS), რიგები + DLQ + rE+ Raplapleacople და გამჭვირვალე დაკვირვება. დააფიქსირეთ კონტრაქტი, შეიყვანეთ ლიმიტები და მეტრიკა, რეგულარულად მოაწყეთ ქაოსი სცენარები - და თქვენი ინტეგრაცია შეჩერდება პირველივე წარუმატებლობის დროს.