Webhooks: təkrar və kvitasiya

1) Əsas çatdırılma modeli

At-least-once (default): hadisə ≥ 1 dəfə çatdırılacaq. Zəmanət alıcının idempotentliyi ilə birdəfəlik əldə edilir.
Kvitasiya (ACK): alıcıdan yalnız hər hansı bir 2xx (adətən 200/204) uğur deməkdir. Qalan hər şey imtina kimi şərh olunur və təkrarlanmasına səbəb olur.
Sürətli ACK: Tam iş emalından sonra deyil, öz növbəsində hadisəni yerləşdirdikdən sonra 2xx cavab verin.

2) Hadisələrin formatı və məcburi başlıqlar

Faydalı yük (nümunə)

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
}

Göndərən başlıqlar

'X-Webhook-Id: evt_01HXYZ' - hadisələrin unikal ID-si (duplikasiya üçün istifadə edin).
'X-Webhook-Seq: 128374' - monoton ardıcıllıq (abunə/mövzu üzrə).
`X-Signature: sha256=<base64(hmac_sha256(body, secret))>` — HMAC-подпись.
'X-Retry: 0,1,2...' - cəhd nömrəsi.
'X-Webhook-Version: 1' - müqavilənin versiyalaşdırılması.
(isteğe bağlı) 'Traceparent' - trasların korrelyasiyası.

Alıcının cavabı

2xx - uğurla qəbul edilmişdir (bu 'id' üçün təkrarlama olmayacaq).
410 Gone - endpoint silindi/aktiv deyil → göndərici təkrar dayandırır və abunəni devre dışı qoyur.
429/5xx/vaxt - göndərici retraj siyasətini təkrarlayır.

3) Təkrarlama siyasəti (retries)

Tövsiyə olunan pilləkən backoff (+ jitter)

'1s, 3s, 10s, 30s, 2m, 10m, 30m, 2h, 6h, 24h' (48-72 saat kimi limitdən sonra dayandırın).

• «Sürü təsirindən» qaçmaq üçün eksponensial backoff + təsadüfi jitter (± 20-30%).
• Müvəqqəti uğursuzluqlar üçün səhv kvorumu (məsələn, 5xx və ya şəbəkə vaxtı varsa təkrar).
• Respect 429: minimum 'min' (Retry-After başlığı, növbəti backoff pəncərəsi) 'qoyun.

Vaxt və ölçülər

Birləşmə vaxtı ≤ 3-5 saniyə; ümumi cavab vaxtı ≤ 10 san.
Bədən ölçüsü (məsələn, 256 KB ≤), əks halda 413 → «chunking» və ya «pull URL» məntiqi.

4) İdempotentlik və duplikasiya

İdempotent tətbiqi: eyni 'id' təkrar emalı eyni nəticəni qaytarmalı və vəziyyəti yenidən dəyişdirməməlidir.
Dedup saxlama alıcı tərəfində: TTL processed_at retraj pəncərələri (24-72 saat) ilə '(X-Webhook-Id, ≥, checksum)' saxlayın.
Kompozisiya açarı: bir neçə topik varsa → '(subscription_id, event_id)'.

5) Sifariş və «exactly-once effektləri»

• Partition by key: Eyni məntiqi çoxluq (məsələn, 'order _ id') həmişə bir «çatdırılma kanalına».
• Sequence: köhnə 'X-Webhook-Seq' ilə hadisələri rədd edin və itkin gələnə qədər onları "parking lot 'a qoyun.

• tətbiq olunan əməliyyatların jurnalı (outbox/inbox pattern),
• əməliyyat upsert 'event _ id' DB-də,
• mürəkkəb proseslər üçün saqi/kompensasiya.

6) Status kodları ilə səhvlərin həlli (cədvəl)

7) Kanal təhlükəsizliyi

Hər bir mesajın HMAC imzası; «vaxt pəncərəsi» (mitm və replay hücumları) ilə alıcıda yoxlama.
həssas domenlər üçün mTLS (KUS/ödənişlər).
IP allowlist çıxış ünvanları, TLS 1. 2+, HSTS.
PII-minimallaşdırma: lazımsız şəxsi məlumatları göndərməyin; lojalarda maskalamaq.
Sirlərin rotasiyası: iki aktiv açar (active/next) və cari göstərilməsi üçün 'X-Key-Id' başlığı.

8) Növbələr, DLQ və repler

Hadisələr mütləq göndərənin tərəfində çıxış növbəsinə/jurnalına yazılır (etibarlı replay üçün).
Maksimum retraj həddini aşdıqda - hadisə səbəb ilə DLQ-yə (Dead Letter Queue) gedir.
Replay API (alıcı/operator üçün): RPS məhdudiyyəti və əlavə imza/avtorizasiya ilə 'id '/zaman diapazonu/mövzu üzrə təkrar göndərmə.

POST /v1/webhooks/replay
{ "subscription_id": "sub_123", "from": "2025-11-03T00:00:00Z", "to": "2025-11-03T12:00:00Z" }
→ 202 Accepted

9) Müqavilə və versiya

Hadisəni versiya edin ('schema _ version' sahəsi) və nəqliyyat ('X-Webhook-Version').
Yalnız isteğe bağlı olaraq sahələr əlavə edin; çıxarıldıqda - minor miqrasiya və keçid dövrü (dual-write).
Hadisə növlərini, nümunələri, sxemləri (JSON Schema), səhv kodlarını sənədləşdirin.

10) Müşahidə və SLO

• 'delivery _ success _ rate' (2xx/bütün cəhdlər), 'first _ 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. Hadisələrin 9% -i ilk ACK ≤ 60 san (28d) alır.

• DLQ ≤ 0. 1% ümumi sayı; DLQ replay ≤ 24 saat.

11) Tayming və şəbəkə qırılması

UTC istifadə edin; NTP sinxronizasiya.
'occurred _ at' göndərin və 'delivered _ at' yazın.
Uzun fasilələrlə şəbəkə/endpoint → növbə yığın, böyüməni məhdudlaşdırın (backpressure + kvotalar).

12) Tövsiyə olunan limitlər və gigiyena

Abunə üçün RPS (məsələn, 50 RPS, burst 100) + paralellik (məsələn, 10).
Maks. bədən: 64-256 KB; daha çox - «notification + URL» və download üçün imza.
'snake' -də hadisələrin adları. case 'və ya' dot. type` (`order. created`).
qəbuledicinin write əməliyyatlarının ciddi idempotentliyi.

13) Nümunələr: göndərən və alıcı

13. 1 Göndərən (psevdokod)

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 Alıcı (psevdokod)

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) Test və xaos təcrübələri

Neqativ hallar: qeyri-sabit imza, 429/5xx, taymaut, 410, böyük payload.
Davranış: out-of-order, dublikatlar, 1-10 dəqiqə gecikmələr, 24 saat fasilə.
Yük: burst 10 ×; backpressure və DLQ sabitliyini yoxlayın.
Müqavilələr: JSON Sxema, məcburi başlıqlar, sabit hadisələr.

15) Giriş çek siyahısı

• 2xx = ACK, və enqueue sonra sürətli geri
• Eksponensial backoff + jitter, hörmət 'Retry-After'
• «X-Webhook-Id» (TTL ≥ retray) üçün alıcı və dedup idempotentlik
• HMAC imzaları, sirlərin rotasiyası, optional mTLS
• DLQ + Replay API, monitorinq və alert
• Məhdudiyyətlər: Taymaut, RPS, bədən ölçüsü
• Sifariş: partition by key və ya 'sequence' + «parking lot»
• Sənədləşmə: sxemlər, nümunələr, səhv kodları, versiyalar
• Xaos testləri: gecikmələr, dubllar, şəbəkə uğursuzluğu, uzun replay

16) Mini-FAQ

Həmişə 200 cavab verməliyəm?
Hər hansı bir 2xx uğur hesab olunur. 202/204 - «növbəyə qəbul» üçün normal təcrübə.

Təkrarları dayandırmaq olarmı?
Bəli, 410 cavab və/və ya göndəricinin konsolu/API vasitəsilə (abunənin bağlanması).

Böyük payloadlar haqqında nə demək olar?
«Bildiriş + secure URL» göndərin, yükləmə sorğusunu imzalayın və TTL qurun.

Nizam-intizamı necə təmin etmək olar?
Partition by key + `sequence`; uyğunsuzluq - «parking lot» və yenidən oynamaq.

Yekun

Etibarlı vebhuklar - ACK (2xx) aydın semantikası, backoff + jitter ilə ağlabatan təkrarlamalar, ciddi idempotentlik və deduplikasiya, səlahiyyətli təhlükəsizlik (HMAC/mTLS), növbələr + DLQ + replica və şəffaf müşahidə. Müqaviləni düzəldin, limitləri və metrikləri daxil edin, müntəzəm olaraq xaos ssenarilərini qaçırın - və inteqrasiyalarınız ilk uğursuzluqlarda «tökülməyi» dayandıracaq.