ვებ ჰუკების მიწოდების გარანტიები

ვებჰუკი - ასინქრონული შეტყობინებები „სისტემიდან აბონენტამდე“ HTTP (S) მიხედვით. ქსელი არასაიმედოა: პასუხები იკარგება, პაკეტები მოდის დუბლიკატებით ან წესრიგის მიღმა. ამრიგად, მიწოდების გარანტიები არ არის აგებული „TCP“ - ით, არამედ ვებჰუკების პროტოკოლის დონეზე და აფეთქების ღუმელის idempotenty.

მთავარი მიზანი: უზრუნველყოს at-least-once- ის მიწოდება ღილაკით (სადაც აუცილებელია), აბონენტს მიაწოდოს მასალები idempotent დამუშავებისთვის და აღდგენის ჩანაწერების ინსტრუმენტი.

1) გარანტიების დონე

Best-effort არის ერთჯერადი მცდელობა, ჭიდაობის გარეშე. მისაღებია მხოლოდ „ცუდი“ მოვლენებისთვის.
At-least-once (რეკომენდებულია) - დუბლიკატები და out-of-order შესაძლებელია, მაგრამ ღონისძიება გადაეცემა იმ პირობით, რომ აბონენტი გონივრულ ვადაში იქნება ხელმისაწვდომი.
Effectively-exactly-once (ეფექტის დონეზე) მიიღწევა აბონენტის/გამგზავნის მხარეს idempotence- ისა და dedup საცავის ერთობლიობით. HTTP „exactly-once“ ტრანსპორტში შეუძლებელია.

2) ვებჰუკის კონტრაქტი: მინიმალური აუცილებელი

X-Webhook-Id: 5d1e6a1b-4f7d-4a3d-8b3a-6c2b2f0f3f21  # глобальный ID события
X-Delivery-Attempt: 3                 # номер попытки
X-Event-Type: payment.authorized.v1          # тип/версия
X-Event-Time: 2025-10-31T12:34:56Z          # ISO8601
X-Partition-Key: psp_tx_987654            # ключ порядка
X-Seq: 418                      # монотонный номер по ключу
X-Signature-Alg: HMAC-SHA256
X-Signature: t=1730378096,v1=hex(hmac(secret, t        body))
Content-Type: application/json

json
{
"id": "5d1e6a1b-4f7d-4a3d-8b3a-6c2b2f0f3f21",
"type": "payment.authorized.v1",
"occurred_at": "2025-10-31T12:34:56Z",
"partition_key": "psp_tx_987654",
"sequence": 418,
"data": {
"payment_id": "psp_tx_987654",
"amount": "10.00",
"currency": "EUR",
"status": "AUTHORIZED"
},
"schema_version": 1
}

ადრესატის მოთხოვნა: უპასუხეთ სწრაფად „2xx“ ხელმოწერის ბუფერიზაციისა და დადასტურების შემდეგ, ხოლო ბიზნესის დამუშავება ასინქრონულია.

3) წესრიგი და მიზეზი

შეკვეთა: გარანტია „არ დატოვებს“ მხოლოდ ერთ 'წვეულებაზე _ კეი' (მაგ., 'player _ id', 'wallet _ id', 'psp _ tx _ id').
გლობალური წესრიგი გარანტირებული არ არის.
გამგზავნის მხარეს არის ხაზი, რომელსაც აქვს სერიის გასაღები (ერთი მომხმარებელი/შარდინგი), მიმღების მხარეს არის inbox s '(წყარო, ღონისძიება _ id) "და სურვილისამებრ ელოდება გამოტოვებული" seq ".

თუ გამოტოვება კრიტიკულია - მიაწოდეთ pull-API 'GET/events? after = checkpoint 'სტატუსისთვის „დაჭერა და გამორთვა“.

4) Idempotence და deduplication

თითოეული ვებჰუკი ახორციელებს სტაბილურ 'X-Webhook-Id'.

მიმღები ინახავს 'inbox (event _ id)': PK - 'source + event _ id'; გამეორება

გვერდითი მოვლენები (ჩანაწერი BD/საფულეში) ხორციელდება მხოლოდ ერთხელ, როდესაც მოვლენის პირველი „ხედვა“ ხდება.
გუნდებისთვის, „ეფექტით“ გამოიყენეთ Idempotency-Key და შედეგების ქეში, რეტრაუსის ფანჯრის განმავლობაში.

5) Retrai, backoff და ფანჯრები

• გადატვირთეთ '5xx/timeout/კავშირი error/409-Conflict (retryable )/429'.
• არ გადაიტანოთ „4xx“ გარდა „409/423/429“ (და მხოლოდ შეთანხმებული სემანტიკით).
• ექსპონენტური backoff + full jitter: 0. 5s, 1s, 2s, 4s, 8s, … მდე 'max = 10-15 წთ'; TTL ჭიდაობის ფანჯრები: მაგალითად, 72 საათი.
• პატივი სცეს 'Retry-After' მიმღებს.
• გქონდეთ ზოგადი ვადა: „აღიარეთ მოვლენა მიწოდების გარეშე“ და გადაიტანეთ იგი DLQ- ში.

yaml retry:
initial_ms: 500 multiplier: 2.0 jitter: full max_delay_ms: 900000 ttl: 72h retry_on: [TIMEOUT, 5xx, 429]

6) DLQ и redrive

DLQ არის შხამიანი ან ამოწურული TTL- ის მოვლენების „სასაფლაო“, სრული მეტაინფორმაციით (payload, სათაურები, შეცდომები, მცდელობები, hesh).
ვებ კონსოლი/API redrive (წერტილის განმეორებითი მიწოდება) არჩევითი კორექტირების/საიდუმლოებით.
პრიორიტეტული ზღვარი და batch-redrive პრიორიტეტული.

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

mTLS (თუ ეს შესაძლებელია) ან TLS 1. 2+.

1. ამოიღეთ 't' (timestamp) სათაურიდან, შეამოწმეთ მოცურების ფანჯარა (მაგალითად, ± 5 წთ).

8) კვოტები, საბადოები და სამართლიანობა

Fair-Queue per tenant/subscriber: ისე, რომ ერთმა აბონენტმა/ტენანტმა არ გაიტანა საერთო აუზი.
კვოტები და burst ლიმიტები გამავალი ტრაფიკისთვის და per-endpoint.
რეაქცია "429" -ზე: პატივი მიაგეთ 'Retry-After- ს ", შეეხოთ ნაკადს; გრძელი ლიმიტით - degrade (მოვლენების მხოლოდ კრიტიკული ტიპების გაგზავნა).

9) გამოწერის სასიცოცხლო ციკლი

Register/Verify: POST endpoint - challenge/response ან out-of-band დადასტურება.
Lease (სურვილისამებრ): ხელმოწერა მოქმედებს 'valid _ to'; გარღვევა მკაფიოა.
Secret rotation: `current_secret`, `next_secret` с `switch_at`.
test ping: ხელოვნური მოვლენა მარშრუტის შესამოწმებლად, ძირითადი ღერძების ჩართვამდე.
ჯანმრთელობის ტესტები: პერიოდული HEAD/GET ლატენტობისა და TLS პროფილის შემოწმებით.

10) სქემების ევოლუცია (მოვლენების ვერსია)

ღონისძიების ტიპის ვერსია: 'payment. authorized. v1` → `…v2`.
ევოლუცია - additive (ახალი ველები - MINOR ვერსია API), breaking - ახალი ტიპი.
სქემის რეესტრი (JSON-Schema/Avro/Protobuf) + ავტომატური ამოცნობა გაგზავნამდე.
სათაური 'X-Event-Type "და ველი" schema _ version "სხეულში - ორივე სავალდებულოა.

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

• `deliveries_total`, `2xx/4xx/5xx_rate`, `timeout_rate`, `signature_fail_rate`.
• 'attempts _ avg', 'p50/p95/p99 _ delivery _ latency _ ms' (პუბლიკაციიდან 2xx- მდე).
• `dedup_rate`, `out_of_order_rate`, `dlq_rate`, `redrive_success_rate`.
• `queue_depth`, `oldest_in_queue_ms`, `throttle_events`.

• მიწოდების წილი არის 60 გ (p95) - 99. 5% კრიტიკული მოვლენებისთვის.
• DLQ ≤ 0. 1% 24 საათისთვის
• Signature failures ≤ 0. 05%.

Логи/трейсинг: `event_id`, `partition_key`, `seq`, `attempt`, `endpoint`, `tenant_id`, `schema_version`, `trace_id`.

12) გამგზავნის რეფერენდუმის ალგორითმი

1. ჩაწერეთ ღონისძიება გარიგების გარეთ.
2. განსაზღვრეთ partition _ key და seq; რიგის განთავსება.
3. Worker იღებს გასაღებს, ქმნის თხოვნას, ხელს აწერს ხელს, აგზავნის ტაიმაუტებით (კონექტირება/რეიდი).
4. „2xx“ - აღიარეთ დისტანციურად, დააფიქსირეთ ლატენტობა და seq-checpoint.
5. „429/5xx/timeout“ - პოლიტიკის შესაბამისად.
6. TTL - DLQ და ალერტის მიხედვით.

13) რეფერენდუმის დამუშავება (მიმღები)

1. მიიღეთ მოთხოვნა, შეამოწმეთ TLS/proto.
2. ხელმოწერის ნამდვილობა და დროის ფანჯრები.
3. სწრაფი ACK 2xx (სინქრონული ჩაწერის შემდეგ ადგილობრივ inbox/ხაზში).
4. ასინქრონული ვორკერი კითხულობს 'inbox' -ს, ამოწმებს 'event _ id' (დედაპლატს), საჭიროების შემთხვევაში, „seq- ს“ ასწორებს 'partition _ key- ში.
5. ასრულებს ეფექტებს, წერს „offset/seq checkpoint“ ჩანაწერისთვის.
6. შეცდომის შემთხვევაში - ადგილობრივი რელეები; „შხამიანი“ დავალებები არის ადგილობრივი DLQ ალერტებით.

14) Reconcile (ტყვია კონტური)

• `GET /events? partition _ key =... & after _ seq =... & limit =... "- მიეცით ყველა გამოტოვებული.
• Token-checkpoint: 'after = opaque _ token' ნაცვლად seq.
• Idempotent redelivery: იგივე 'event _ id', იგივე ხელმოწერა ახალ 't- ზე.

15) სასარგებლო სათაურები და კოდები

2xx - მიიღო (თუნდაც ბიზნესის დამუშავება მოგვიანებით).
410 Gone - endpoint დახურულია (გამგზავნი წყვეტს მიწოდებას და ასახელებს გამოწერას, როგორც „არქივში“).
409/423 - რესურსის დროებითი დაბლოკვა გონივრული.
429 - ძალიან ხშირად trottle და backoff.
400/401/403/404 - კონფიგურაციის შეცდომა; შეაჩერეთ ტრეისი, გახსნათ ტიკეტი.

16) მულტფილმები და რეგიონები

ინდივიდუალური ხაზები და ლიმიტები per tenant/endpoint.
მონაცემთა აღდგენა: მონაცემთა გაგზავნა რეგიონიდან; 'X-Tenant', 'X-Region' სათაურები.
გაუმართაობის იზოლაცია: ერთი აბონენტის დაცემა გავლენას არ ახდენს დანარჩენზე.

17) ტესტირება

Contract tests: ცხედრების/ხელმოწერების ფიქსირებული მაგალითები, ვალიდაციის შემოწმება.
ქაოსი: ფრაგმენტები/დუბლიკატები, შეკვეთის შეკვეთა, ქსელის შეფერხება, 'RST', 'TLS' სისხლჩაქცევები.
Load: burst ქარიშხალი, გაზომეთ p95/p99.
უსაფრთხოება: ანტი-მიმღები, მოძველებული timestamp, არასწორი საიდუმლოებები, როტაცია.
DR/Replay: მასიური redrive DLQ- დან იზოლირებულ სტენდში.

18) Playbooks (runbooks)

1. ზრდა 'signature _ fail _ rate'

შეამოწმეთ საათის დრიფტი, ამოიწურა 'tolerance', საიდუმლოებების როტაცია; დროებით ჩართეთ „ორმაგი საიდუმლო“.

2. რიგი დაბერდება ('oldest _ in _ queue _ ms')

გაზარდეთ ვორკერები, ჩართეთ კრიტიკული ღუმელების პრიორიტეტი, დროებით შეამციროთ „ხმაურიანი“ ტიპების სიხშირე.

3. ქარიშხალი '429' აბონენტისგან

ჩართეთ trotling და პაუზები მცდელობებს შორის; ნაკლებად კრიტიკული მოვლენების გადატანა.

4. მასობრივი „5xx“

გახსენით circuit-breaker კონკრეტული endpoint- ისთვის, გადაიტანეთ defer & batch რეჟიმში; აბონენტის სიგნალი.

5. DLQ შევსება

შეაჩერეთ არა კრიტიკული პუბლიკაცია, ჩართეთ batch-redrive დაბალი RPS- ით, აიღეთ ალერტები აბონენტების მფლობელებისთვის.

19) ტიპიური შეცდომები

სინქრონული მძიმე დამუშავება 2xx რეაგირებისა და დუბლიკატების პასუხამდე.
არ არსებობს სხეულის/დროის ფანჯრის ხელმოწერა, ჩანაცვლების/მიმღების დაუცველობა.
'event _ id' და 'inbox' არარსებობა შეუძლებელია იდემპოტენტურობის გაკეთება.
„გლობალური წესრიგის“ მცდელობა რიგების მარადიული დაბლოკვა.
Retrai გარეშე jitter/limites - ინციდენტის გაძლიერება.
ყველა აბონენტისთვის ერთი საერთო აუზი - „ხმაურიანი“ ყველას აყენებს.

20) ჩეკის სია გაყიდვამდე

• კონტრაქტი: 'event _ id', 'partition _ key', 'seq', 'event _ ტიპი. vN ', HMAC და Timestamp- ის ხელმოწერა.
• გამგზავნი: Outbox, სერიის გასაღები, retrais backoff + jitter, TTL, DLQ და redrive.
• მიმღები: სწრაფი ჩანაწერი inbox + 2xx; იდემპოტენტური დამუშავება; ადგილობრივი DLQ.
• უსაფრთხოება: TLS, ხელმოწერები, ანტი-მიმღები, ორმაგი საიდუმლო, როტაცია.
• კვოტები/ლიმიტები: სამართლიანი დედოფალი per tenant/endpoint, პატივისცემა 'Retry-After'.
• Reconcile API და checpoints; დოკუმენტაცია აბონენტებისთვის.
• დაკვირვება: p95/ნაკადები/შეცდომები/DLQ, event _ id ტრეკერი.
• მოვლენების ვერსია და სქემების ევოლუციის პოლიტიკა.
• ინციდენტების ფლეიბუკი და გლობალური პაუზის/გაყინვის „ღილაკი“.

დასკვნა

საიმედო ვებჰუკი არის პროტოკოლი HTTP თავზე და არა მხოლოდ „POST JSON“. მკაფიო კონტრაქტი (ID, წესრიგის გასაღები, ხელმოწერა), idempotence, retrais ერთად jitter, სამართლიანი რიგები და კარგად კოორდინირებული playbucks „საუკეთესო შემთხვევად“ იქცევა პროგნოზირებად და გაზომილ მიწოდების მექანიზმად. ააშენეთ at-least-once + საკვანძო ბრძანება + reconcile და სისტემა მშვიდად გადაურჩება ქსელს, დატვირთვის მწვერვალებს და ადამიანის შეცდომებს.