Webhook teslimat garantileri

Webhook'lar HTTP (S) üzerinden asenkron sistemden aboneye bildirimlerdir. Ağ güvenilmezdir: yanıtlar kaybolur, paketler yinelenir veya düzensiz gelir. Bu nedenle, teslimat garantileri "TCP üzerinden'değil, webhook protokolü ve domain idempotency düzeyinde oluşturulur.

Temel amaç: Anahtar ile sipariş ile en az bir kez teslimat sağlamak (gerektiğinde), aboneye idempotent işleme için materyaller ve geri yüklemeler için bir uzlaştırma aracı vermek.

1) Garanti seviyeleri

En iyi çaba - retras olmadan bir kerelik bir girişim. Sadece "önemsiz" olaylar için kabul edilebilir.
En az bir kez (önerilen) - kopyalar ve sıra dışı durumlar mümkündür, ancak abonenin makul bir süre içinde mevcut olması koşuluyla olay teslim edilecektir.
Etkili-tam olarak-bir kez (etki düzeyinde) - abone/gönderici tarafında idempotency ve dedup depolama kombinasyonu ile elde edilir. "Tam olarak bir kez" HTTP aktarımı mümkün değildir.

2) Webhook sözleşmesi: minimum gerekli

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ı için gereklilik: imzayı tamponladıktan ve doğruladıktan sonra hızlı bir şekilde '2xx' yanıt verin ve iş işlemlerini eşzamansız olarak yapın.

3) Düzen ve nedensellik

Anahtar sırası: garanti "bırakmayacak" sadece bir 'partition _ key' içinde (örn. 'oyuncu _ id', 'cüzdan _ id', 'psp _ tx _ id').
Küresel düzen garanti değildir.
Gönderen tarafında, anahtarla (bir tüketici/sharding) serileştirilmiş bir kuyruk var, alıcı tarafında '(kaynak, event_id)' içeren bir gelen kutusu var ve isteğe bağlı olarak eksik 'seq' bekliyor.

Boşluklar kritik ise - pull-API 'GET/olayları sağlayın? "yetişmek ve danışmak" için = kontrol noktasından sonra.

4) Idempotency ve veri tekilleştirme

Her webhook kararlı bir 'X-Webhook-Id' taşır.
Alıcı 'gelen kutusu (event_id)' saklar: PK - 'kaynak + event_id'; No-op tekrarlar.
Yan etkiler (veritabanına/cüzdana yazma), olay ilk "görüldüğünde" yalnızca bir kez gerçekleştirilir.
Etkili komutlar için, Idempotency-Key ve sonuç önbelleğini retray penceresinin süresi boyunca kullanın.

5) Retrai, backoff ve pencereler

• '5xx/timeout/connection error/409-Conflict (retryable )/429' moduna geçin.
• '4xx' üzerinde '409/423/429' dışında (ve sadece tutarlı semantik ile) geri çekilmeyin.
• Üstel geri dönüş + tam titreme: 0. 5s, 1s, 2s, 4s, 8s,... 'max = 10-15 dk'ya kadar; TTL geri ödeme pencereleri: örneğin, 72 saat.
• Alıcıdan gelen 'Retry-After'a saygı gösterin.
• Ortak bir son teslim tarihine sahip olun: "olayın teslim edilmediğini kabul edin've DLQ'ya aktarı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 bilgi (yük, başlıklar, hatalar, girişimler, karma) içeren zehirli veya TTL süresi dolmuş olayların "mezarlığı".
İsteğe bağlı uç nokta/gizli düzenleme ile redrive (nokta yeniden teslim) için Web konsolu/API.
Oranı sınırlı redrive ve toplu redrive öncelikli.

7) Güvenlik

mTLS (mümkünse) veya TLS 1. 2+.

1. Başlıktan't '(zaman damgası) çıkarın, sürgülü pencereyi kontrol edin (örneğin, ± 5 dakika).

8) Kotalar, oran limitleri ve eşitlik

Kiracı/abone başına adil kuyruk: böylece bir abone/kiracı genel havuzu puanlamaz.
Giden trafik ve uç nokta başına kotalar ve patlama sınırları.
'429'a tepki: onur' Retry-After ', trol akışı; Uzun vadeli sınırlama için - degrade (sadece kritik olay türlerini gönderme).

9) Abonelik yaşam döngüsü

Register/Verify: POST endpoint> challenge/response veya out-of-band confirmation.
Kiralama (isteğe bağlı): imza 'valid _ to'ya kadar geçerlidir; Uzama - açık.
Gizli rotasyon: 'current _ secret', 'next _ secret' с 'switch _ at'.
Test ping: Ana konuları açmadan önce rotayı test etmek için yapay bir olay.
Sağlık örnekleri: Gecikme ve TLS profil kontrolü ile periyodik HEAD/GET.

10) Şemaların evrimi (olay versiyonları)

Sürüm oluşturma olay türü: 'ödeme. yetkilendirildi. v1 '-'... v2 '.
Evolution - additive (yeni alanlar - MINOR API sürümleri), breaking - yeni bir tür.
Şema kaydı (JSON-Schema/Avro/Protobuf) + gönderilmeden önce otomatik doğrulama.
Gövdedeki 'X-Event-Type' başlığı ve 'schema _ version' alanının her ikisi de gereklidir.

11) Gözlemlenebilirlik ve SLO

• 'deliveries _ total', '2xx/4xx/5xx _ rate', 'timeout _ rate', 'signature _ fail _ rate'.
• 'attacks _ avg', 'p50/p95/p99 _ delivery _ latency _ ms' (2xx'e yayınla).
• 'debup _ rate', 'out _ of _ order _ rate', 'dlq _ rate', 'redrive _ success _ rate'.
• 'eue _ depth','en eski _ in _ queue _ ms ',' throttle _ events '.

• Teslimatların payı ≤ 60 s (p95) - 99. Kritik olaylar için %5.
• DLQ ≤ 0. 24 saatte %1
• İmza hataları ≤ 0. 05%.

Логи/трейсинг: 'event _ id', 'partition _ key', 'seq', 'entry', 'endpoint', 'tenant _ id', 'schema _ version', 'trace _ id'.

12) Gönderen referans algoritması

1. İşlem giden kutusuna olay yaz.
2. partition_key ve seq tanımlamak; kuyruk.
3. İşçi anahtarla alır, bir istek oluşturur, işaretler, zaman aşımlarıyla gönderir (bağlan/oku).
4. '2xx'ile - teslim olarak tanımak, gecikme ve seq-checkpoint düzeltmek.
5. '429/5xx/timeout'ile - politikaya göre geri çekilme.
6. TTL - DLQ ve uyarı ile.

13) Referans işlemci (alıcı)

1. İsteği kabul edin, TLS/proto'yu kontrol edin.
2. İmza ve zaman penceresinin doğrulanması.
3. Hızlı ACK 2xx (yerel gelen kutusuna/kuyruğa eşzamanlı yazdıktan sonra).
4. Eşzamansız çalışan 'gelen kutusu'nu okur,' event _ id '(büyükbaba)'yi kontrol eder, gerekirse' seq 'inside' partition _ key'ile emir verir.
5. Efektler gerçekleştirir, uzlaştırmak için "offset/seq checkpoint" yazar.
6. Hata durumunda - yerel retrays; "zehirli" görevler - uyarılarla yerel DLQ.

14) Uzlaştırın (havuz döngüsü)

• 'GET/olaylar? partition_key=...&after_seq=...&limit=...' - tüm özlenenleri vermek için.
• Belirteç kontrol noktası: seq yerine 'after = opaque _ token'.
• Idempotent redelivery: aynı'olay _ id ', yeni't' üzerinde aynı imza.

15) Faydalı başlıklar ve kodlar

2xx - kabul edilir (iş işleme daha sonra olsa bile).
410 Gone - uç nokta kapatılır (gönderen teslimatı durdurur ve aboneliği "arşivlenmiş'olarak işaretler).
409/423 - kaynağın geçici olarak bloke edilmesi - yeniden ödeme makul.
429 - çok sık - gaz ve geri tepme.
400/401/403/404 - yapılandırma hatası; Retrai'yi durdur, bileti aç.

16) Çok kiracı ve bölgeler

Kiracı/uç nokta başına bireysel kuyruklar ve sınırlar.
Veri ikameti: bölgeden veri gönderme; Uçtan uca 'X-Tenant', 'X-Region' başlıkları.
Arızaların izolasyonu: Bir abonenin düşmesi geri kalanını etkilemez (ayrı havuzlar).

17) Test etme

Sözleşme testleri: sabit organ/imza örnekleri, doğrulama kontrolü.
Kaos: drop/duplicates, shuffle düzeni, ağ gecikmeleri, 'RST', 'TLS' hataları.
Yük: patlama-fırtına, p95/p99 ölçüldü.
Güvenlik: anti-tekrar, eski zaman damgası, yanlış sırlar, rotasyon.
DR/Replay: İzole standda DLQ'dan kütle redrive.

18) Playbook'lar (runbook'lar)

1. Growth 'signature _ fail _ rate'

Saat kaymasını, süresi dolmuş 'toleransı', sırların dönüşünü kontrol edin; Geçici olarak "ikili sırrı" etkinleştirin.

2. Kuyruk yaşlanıyor ('en eski _ in _ queue _ ms '↑)

Çalışanları artırın, kritik konuların önceliklendirilmesini sağlayın, "gürültülü" türlerin sıklığını geçici olarak azaltın.

3. Fırtına '429' abonede

Girişimler arasında kısma ve duraklamaları etkinleştirin; Daha az kritik olay türlerini kaydırın.

4. Kütle '5xx'

Belirli bir uç nokta için açık devre kesici, ertelemeye geçiş & toplu; aboneye sinyal.

5. DLQ doldur

Kritik olmayan yayınlamayı durdurun, düşük RPS ile toplu işlemi etkinleştirin, abonelik sahiplerine uyarılar yükseltin.

19) Tipik hatalar

2xx yanıtına senkron ağır işlem - retrays ve kopyalar.
Gövde/zaman penceresi imzası yok - değiştirme/yeniden oynatma güvenlik açığı.
'Event _ id've' inbox 'yokluğu idempotent yapılamaz.
"Küresel düzen" girişimi - sonsuz kuyruk kilitleri.
Titremesiz/limitsiz geri çekilmeler - olay yoğunlaşması (gürleyen sürü).
Tüm aboneler için tek bir ortak havuz - "gürültülü" herkesi koyar.

20) Satış öncesi kontrol listesi

• Sözleşme: 'event _ id', 'partition _ key', 'seq', 'event _ type. vN ', HMAC imzası ve zaman damgası.
• Gönderen: giden kutusu, anahtarla serileştirme, backoff + jitter, TTL, DLQ ve redrive ile retrays.
• Alıcı: gelen kutusuna hızlı yazma + 2xx; Idempotent tedavi; Yerel DLQ.
• Güvenlik: TLS, imzalar, anti-replay, çift gizli, rotasyon.
• Kotalar/sınırlar: kiracı/uç nokta başına adil kuyruk, saygı 'Retry-After'.
• API'leri ve kontrol noktalarını uzlaştırın; aboneler için belgeler.
• Gözlemlenebilirlik: p95/threads/errors/DLQ, trace to 'event _ id'.
• Olay sürüm oluşturma ve şema evrim politikası.
• Olay oyun kitapları ve küresel duraklat/buz çözme düğmesi.

Sonuç

Güvenilir webhook'lar HTTP'nin üstünde bir protokoldür, sadece "JSON ile POST. "Açık bir sözleşme (kimlik, sipariş anahtarı, imza), idempotency, jitter ile yeniden ödeme, adil kuyruk ve iyi hata ayıklanmış playbook'lar en iyi durumu öngörülebilir ve ölçülebilir bir dağıtım mekanizmasına dönüştürür. En az bir kez + anahtar sipariş + uzlaştırmak inşa ve sistem sakince ağ, yük zirveleri ve insan hataları hayatta kalacaktır.