Webhook çatdırılma zəmanətləri

Vebhuklar - HTTP (S) vasitəsilə «sistemdən abunəçiyə» asinxron bildirişlər. Şəbəkə etibarsızdır: cavablar itirilir, paketlər dublikatlarla və ya sıradan çıxır. Buna görə də çatdırılma zəmanəti «TCP» ilə deyil, vebhuk protokolu və domen idempotentliyi səviyyəsində qurulur.

Əsas məqsəd: açar sifarişi ilə at-least-once çatdırılmasını təmin etmək (lazım olan yerdə), abunəçiyə empotent emalı üçün materiallar və bərpa üçün reconcile aləti vermək.

1) Zəmanət səviyyələri

Best-effort - retrajlar olmadan birdəfəlik cəhd. Yalnız «əhəmiyyətsiz» hadisələr üçün məqbuldur.
At-least-once (tövsiyə olunur) - dublikatlar və out-of-order mümkündür, lakin abunəçinin məqbul müddətdə mövcud olması şərti ilə hadisə çatdırılacaq.
Effectively-exactly-once (effekt səviyyəsində) - abunəçi/göndərici tərəfində idempotentlik və dedup-saxlama kombinasiyası ilə əldə edilir. HTTP nəqliyyatında «exactly-once» mümkün deyil.

2) Vebhuk müqaviləsi: minimum zəruri

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
}

Alıcıya tələb: imzanı tamponladıqdan və təsdiqlədikdən sonra tez '2xx' cavab vermək və biznes emalını asenxron etmək.

3) Sifariş və səbəb

Açar qaydası: zəmanət yalnız bir 'partition _ key' daxilində «getməyəcək» (məsələn, 'player _ id', 'wallet _ id', 'psp _ tx _ id').
Qlobal qaydaya zəmanət verilmir.
Göndərənin tərəfində - açar seriyallaşdırılması (bir istehlakçı/şardinq), alıcının tərəfində - inbox c '(source, event_id)' və əlavə olaraq buraxılmış 'seq' gözləmə.

Əgər boşluqlar kritikdirsə - pull-API 'GET/events verin? after = checkpoint 'statusu üçün «tutmaq və yoxlamaq».

4) İdempotentlik və duplikasiya

Hər vebhuk sabit 'X-Webhook-Id' daşıyır.
Alıcı 'inbox (event_id)' saxlayır: PK - 'source + event_id'; → no-op təkrar.
Yan təsirlər (DB/cüzdan qeydləri) hadisənin ilk «görünüşü» ilə yalnız bir dəfə həyata keçirilir.
Effektli komandalar üçün Idempotency-Key və retraj pəncərəsi zamanı nəticə cache istifadə edin.

5) Retray, backoff və pəncərələr

• Retraj '5xx/timeout/connection error/409-Conflict (retryable )/429'.
• '409/423/429' istisna olmaqla '4xx' üzərində retraj etməyin (və yalnız razılaşdırılmış semantika ilə).
• Eksponensial backoff + full jitter: 0. 5s, 1s, 2s, 4s, 8s, … 'max = 10-15 dəq'; TTL pəncərə retrains: məsələn, 72 saat.
• Alıcının 'Retry-After' hörmət.
• Ortaq bir son tarixə sahib olun: «hadisəni çatdırılmamış hesab edin» və onu DLQ-yə köçürün.

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 - tam meta məlumatlarla (paiload, başlıqlar, səhvlər, cəhdlər, heşlər) zəhərli və ya TTL-dən keçən hadisələrin «qəbiristanlığı».
Veb konsol/API üçün redrive (nöqtəli təkrar çatdırılma) ilə opsiyonel düzəliş endpoint/secret.
Rate-limited redrive və batch-redrive prioritetləşdirilməsi ilə.

7) Təhlükəsizlik

mTLS (mümkünsə) və ya TLS 1. 2+.

1. Başlıqdan 't' (timestamp) çıxarın, sürüşmə pəncərəsini yoxlayın (məsələn, ± 5 dəq).

8) Kvotalar, rate limits və ədalət

Fair-Queue per tenant/subscriber: bir abunəçi/tenant ümumi hovuzu vurmamalıdır.
Gedən trafik və per-endpoint üçün kvotalar və burst-limitlər.
Reaksiya '429': oxu 'Retry-After', trotlit axını; uzunmüddətli məhdudlaşdırmada - degrade (yalnız kritik hadisə növlərinin göndərilməsi).

9) Abunə həyat dövrü

Register/Verify: POST endpoint → challenge/response və ya out-of-band təsdiq.
Lease (isteğe bağlı): imza 'valid _ to' qədər etibarlıdır; uzadılması - aşkar.
Secret rotation: `current_secret`, `next_secret` с `switch_at`.
Test ping: əsas topiklər daxil etməzdən əvvəl marşrutu yoxlamaq üçün süni hadisə.
Sağlamlıq testləri: latency və TLS profil yoxlama ilə periodik HEAD/GET.

10) Sxemlərin təkamülü (hadisələrin versiyaları)

Hadisə növü versiyası: 'payment. authorized. v1` → `…v2`.
Təkamül - additive (yeni sahələr → API MINOR versiyası), breaking → yeni növü.
Sxemlərin qeydiyyatı (JSON-Schema/Euro/Protobuf) + göndərilmədən əvvəl avtomatik validasiya.
«X-Event-Type» başlığı və «schema _ version» sahəsi - hər ikisi tələb olunur.

11) Müşahidə və SLO

• `deliveries_total`, `2xx/4xx/5xx_rate`, `timeout_rate`, `signature_fail_rate`.
• 'attempts _ avg', 'p50/p95/p99 _ delivery _ latency _ ms' (nəşrdən 2xx-ə qədər).
• `dedup_rate`, `out_of_order_rate`, `dlq_rate`, `redrive_success_rate`.
• `queue_depth`, `oldest_in_queue_ms`, `throttle_events`.

• Çatdırılma payı ≤ 60 c (p95) - 99. 5% kritik hadisələr üçün.
• DLQ ≤ 0. 1% 24 saat ərzində
• Signature failures ≤ 0. 05%.

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

12) Göndərənin istinad alqoritmi

1. Hadisəni əməliyyat outbox-a yazın.
2. partition_key və seq müəyyən edin; növbəyə qoyun.
3. Worker açar alır, sorğu formalaşdırır, imza atır, taymautlarla göndərir (connect/read).
4. Zaman '2xx' - çatdırılmış kimi tanımaq, gizli və seq-check-point qeyd.
5. '429/5xx/timeout' - siyasətə uyğun olaraq retraj.
6. TTL → DLQ və alert.

13) Referens prosessor (alıcı)

1. Sorğunu qəbul edin, TLS/proto-nu yoxlayın.
2. İmza və vaxt pəncərəsinin təsdiqlənməsi.
3. Sürətli ACK 2xx (yerli inbox/növbə sinxron qeyd sonra).
4. Asenxron vorker 'inbox' oxuyur, 'event _ id' (dedup) yoxlayır, lazım gələrsə 'seq' daxilində 'partition _ key' ilə nizamlayır.
5. Effektləri yerinə yetirir, reconcile üçün «offset/seq kontrol nöqtəsi» yazır.
6. Səhv olduqda - yerli retralar; «zəhərli» vəzifələr → alertlər ilə lokal DLQ.

14) Reconcile (pull-kontur)

• `GET /events? partition_key=...&after_seq=...&limit=...' - bütün buraxılmış vermək.
• Token kontrol nöqtəsi: seq əvəzinə 'after = opaque _ token'.
• İdempotent redelivery: eyni 'event _ id', eyni imza yeni 't'.

15) Faydalı başlıqlar və kodlar

2xx - qəbul (hətta daha sonra iş emalı).
410 Gone - endpoint bağlandı (göndərici çatdırılmasını dayandırır və abunəni «arxivə» kimi qeyd edir).
409/423 - resursun müvəqqəti bloklanması → retraj ağıllı.
429 - çox tez-tez → trottl və backoff.
400/401/403/404 - konfiqurasiya səhvi; retrai dayandırmaq, bilet açmaq.

16) Multi-tenant və regionlar

Ayrı-ayrı növbələr və limitlər per tenant/endpoint.
Data residency: bölgədən məlumat göndərilməsi; «X-Tenant», «X-Region» başlıqları.
Uğursuzluqların izolyasiyası: bir abunəçinin düşməsi digərlərinə təsir etmir (separate pools).

17) Test

Contract tests: sabit telefon/imza nümunələri, validasiya yoxlama.
Chaos: drop/dublikatlar, shuffle sifariş, gecikmə şəbəkəsi, 'RST', 'TLS' -hata.
Load: burst fırtına, p95/p99 ölçü.
Təhlükəsizlik: anti-replay, köhnəlmiş timestamp, səhv sirləri, rotasiya.
DR/Replay: izolyasiya stendində DLQ-dən kütləvi redrive.

18) Playbooks (runbooks)

1. 'signature _ fail _ rate'

Saat sürüklənməsini, bitmiş 'tolerance', sirlərin rotasiyasını yoxlamaq; müvəqqəti olaraq «dual secret».

2. Növbə qocalır ('oldest _ in _ queue _ ms' ↑)

İşçilər artırın, kritik topiklərin prioritetləşdirilməsini daxil edin, müvəqqəti olaraq «səs-küylü» tiplərin tezliyini azaltın.

3. Fırtına '429' abunəçi

Trottling və cəhdlər arasında fasilələr daxil edin; daha az kritik hadisə növləri hərəkət.

4. Kütləvi '5xx'

Xüsusi end point üçün circuit-breaker açın, defer & batch rejiminə keçin; abunəçiyə siqnal.

5. DLQ doldurma

Kritik olmayan yayımı dayandırın, aşağı RPS ilə batch-redrive daxil edin, abunə sahiblərinin həyəcanını artırın.

19) Tipik səhvlər

Cavab üçün sinxron ağır emal 2xx → retray və təkrarlanır.
Heç bir imza bədən/vaxt pəncərə → həssaslıq/replay.
'event _ id' və 'inbox' → olmaması idempotentlik etmək mümkün deyil.
«Qlobal nizam» cəhd → əbədi bloklama növbələri.
Jitter/limitsiz retray → hadisənin gücləndirilməsi (thundering herd).
Bütün abunəçilər üçün vahid ümumi hovuz → «səs-küylü» hamını qoyur.

20) Satış öncəsi yoxlama siyahısı

• Müqavilə: 'event _ id', 'partition _ key', 'seq', 'event _ type. vN ', imzası HMAC və timestamp.
• Göndərən: outbox, açar seriyası, backoff + jitter, TTL, DLQ və redrive ilə retrailer.
• Alıcı: inbox + 2xx sürətli qeyd; idempotent emalı; yerli DLQ.
• Təhlükəsizlik: TLS, imzalar, anti-replay, dual-secret, rotasiya.
• Kvotalar/limitlər: fair-queue per tenant/endpoint, hörmət 'Retry-After'.
• Reconcile API və kontrol nöqtələri; abunəçilər üçün sənədləşmə.
• Müşahidə: p95/axınlar/səhvlər/DLQ, izləmə 'event _ id'.
• Hadisələrin versiyalaşdırılması və sxemlərin təkamül siyasəti.
• Hadisələrin playbook və qlobal fasilə/ərimə «düyməsi».

Nəticə

Etibarlı vebhuklar sadəcə «JSON ilə POST» deyil, HTTP üzərindəki protokoldur. Aydın müqavilə (ID, sifariş açarı, imza), idempotentlik, jitter retrayları, ədalətli növbə və yaxşı tənzimlənmiş playbuklar "ən yaxşı hal 'ı proqnozlaşdırıla bilən və ölçülə bilən çatdırılma mexanizminə çevirir. At-least-once + açar sifarişi + reconcile qurun və sistem sakitcə şəbəkədən, yükün zirvələrindən və insan səhvlərindən sağ çıxacaq.