Webhook'lara dair en yaygın yanılgı, onların güvenilir bir haberci olduğunu sanmaktır. Ödeme sağlayıcı bildirim gönderir, senin uç noktan alır, sipariş teslim edilir; akış kağıt üzerinde kusursuz görünür. Gerçekte ise webhook, tek yönlü ve sonucu belirsiz bir mektuptur. Yolda kaybolabilir, iki kez gelebilir, sıra dışı gelebilir ya da senin sunucun tam o anda dağıtım yapıyor olduğu için hiç ulaşmayabilir. Hiçbiri istisnai durum değil; hepsi rutindir.
Bu yüzden asıl mesele webhook almak değil, alamadığında ne olacağını tasarlamaktır. Tekrar deneme stratejisi tam olarak bunun adıdır ve iki yönü vardır: sana gelen bildirimleri nasıl karşılayacağın, bir de senin başkalarına gönderdiğin bildirimleri nasıl tekrar deneyeceğin. Olgun bir dijital ürün satış scripti her iki yönü de ayrı ayrı ele alır. Bu yazıda hangi bekleme eğrisinin işe yaradığını, idempotency anahtarını nereye koyacağını, imza doğrulamayı tekrar denemeyle nasıl birlikte kuracağını ve ne zaman vazgeçmen gerektiğini anlatıyorum.
Webhook'u Gönderdim Gerisi Beni İlgilendirmez Demenin Bedeli
Gönderen taraf olduğunda, karşı sistemin 200 döndürmesi işin tamamlandığı anlamına gelmez; sadece bildirimin teslim edildiği anlamına gelir. Karşı taraf 500 dönerse, ya da hiç dönmezse, elinde iki seçenek vardır: bırakmak veya tekrar denemek. Bırakmak ucuz görünür ama bedeli sessizdir; bayilerin siparişlerinin bir kısmı hiç işlenmez ve kimse nedenini bilemez.
Doğru kurgu, her webhook gönderimini kalıcı bir kayda dönüştürmektir. Kayıt şu alanları tutar: hedef adres, gövde, imza, deneme sayısı, son yanıt kodu, son hata metni ve bir sonraki deneme zamanı. Böylece gönderim bir "anlık olay" olmaktan çıkıp izlenebilir bir işe dönüşür. Bu kaydı tutmayan bir e-pin yazılımı sorun yaşandığında kanıt üretemez; müşteriyle "ben gönderdim", "ben almadım" tartışmasına girer. Kayıt varsa tartışma biter, log konuşur.
Neden Sabit Aralıklı Tekrar Denemek Sorunu Büyütür?
En sık görülen hata, başarısız gönderimi her dakika tekrar denemektir. Karşı sistem geçici olarak yoğun olduğu için hata veriyorsa, sen de dakikada bir istek ekleyerek onu daha da yorarsın. Bu davranışa gürültülü komşu denir ve iki tarafın da iyileşmesini geciktirir. Üstelik binlerce kayıt biriktiğinde kendi kuyruğunu da sabit yükle doldurursun.
Sağlıklı yaklaşım artan beklemedir: 5 saniye, 30 saniye, 2 dakika, 10 dakika, 1 saat, 6 saat. Bu eğri hem geçici hataları hızlı toparlar hem de kalıcı hatalarda sistemi rahat bırakır. Buna bir de rastgele sapma eklemelisin. Aynı anda başarısız olan bin gönderim, aynı formülü kullandığı için tam aynı saniyede tekrar denenir ve karşı tarafı ikinci kez devirir. Her beklemeye yüzde on ile yirmi arası rastgele bir pay eklemek bu dalgayı dağıtır. Bu detay küçük görünür ama büyük kurulumlarda fark yaratır; bir e-pin satış yazılımı için bayi sayısı büyüdükçe zorunlu hale gelir.
| Deneme | Bekleme | Toplam geçen süre | Bu aşamada beklenen durum |
|---|---|---|---|
| 1 | anında | 0 sn | Normal teslimat |
| 2 | 5 sn | 5 sn | Anlık ağ dalgalanması |
| 3 | 30 sn | 35 sn | Karşı tarafta kısa yoğunluk |
| 4 | 2 dk | 2,5 dk | Dağıtım veya yeniden başlatma |
| 5 | 10 dk | 13 dk | Kısa süreli kesinti |
| 6 | 1 sa | 1,2 sa | Ciddi arıza, insan uyarısı |
| 7 | 6 sa | 7 sa | Son şans, sonra ölü harf |
İdempotency Anahtarı Olmayan Bir Webhook Kurulumu Neden Bomba?
Tekrar deneme, doğası gereği mükerrer teslimat üretir. Karşı taraf isteği aldı, işledi, tam yanıt dönerken bağlantı koptu. Sen yanıt görmediğin için tekrar denersin; o ise isteği ikinci kez işler. Sonuç: iki kod, iki bakiye hareketi ya da iki iade. Bu olasılık teorik değil, tekrar denemenin kaçınılmaz yan etkisidir.
Çözüm her bildirime tekil ve sabit bir olay kimliği koymaktır. Aynı gönderim kaç kez denenirse denensin kimlik değişmez. Alan taraf bu kimliği tekil kısıtlı bir tabloya yazar; ikinci kez geldiğinde yazma başarısız olur ve bildirim sessizce yok sayılıp 200 döner. Dikkat: yok sayılan mükerrer bildirime hata dönmek yanlıştır, çünkü gönderen bunu başarısızlık sanıp tekrar dener. Kendi uç noktanı yazarken de kuralı aynı kur: önce kimliği kaydet, sonra işi yap. Bu sıralamayı ters çevirirsen koruma çalışmaz.
Başarısız webhook denemelerinin nedenleri
- Alıcı tarafta zaman aşımı 50%
- Geçici 5xx ve dağıtım kesintisi 25%
- İmza veya gövde uyuşmazlığı 15%
- Yanlış veya eskimiş adres 10%
İmza Doğrulama: Tekrar Denemenin Güvenlik Tarafı
Tekrar denenen bir bildirim, saldırgan için tekrar oynatma fırsatıdır. Ağı dinleyen biri geçerli bir bildirimi yakalayıp yüz kez sana geri gönderebilir. İmza doğrulaması olmadan bu isteklerin hepsi meşru görünür. Bu yüzden her bildirimin gövdesi, paylaşılan bir gizli anahtarla imzalanmalı ve imza gövdenin ham hali üzerinden hesaplanmalıdır. Gövdeyi ayrıştırıp yeniden birleştirdikten sonra imzalamak, boşluk ve sıralama farkları nedeniyle doğrulamayı rastgele kırar.
İkinci koruma zaman damgasıdır. İmzanın içine bildirim zamanını dahil eder ve beş dakikadan eski damgaları reddedersin. Böylece yakalanan eski bir istek sonsuza kadar kullanılamaz. Üçüncü koruma, imza karşılaştırmasını sabit zamanlı yapmaktır; sıradan bir eşitlik karşılaştırması, karakter karakter erken çıktığı için anahtar hakkında ipucu verir. Bu üç önlem birlikte, tekrar deneme mekanizmasını saldırı yüzeyi olmaktan çıkarır. Pinova'nın bildirim katmanındaki imza ve olay kimliği kurgusunu özellikler bölümünden inceleyebilirsin.
Ölü Harf Kuyruğu: Vazgeçmeyi Bilmek de Strateji
Sonsuza kadar tekrar denemek sorumluluk değil, ihmaldir. Yedi denemeden sonra hâlâ başarısız olan bir bildirim artık teknik bir sorun değil, insan müdahalesi gerektiren bir vakadır. Bu noktada iş ölü harf kuyruğuna taşınır: denemeler durur, kayıt saklanır ve yöneticiye bildirim gider.
Ölü harf kuyruğunu değerli kılan şey, elle yeniden gönderme yeteneğidir. Bayi adresini düzelttikten sonra tek tuşla o bildirimi yeniden kuyruğa atabilmelisin; tüm geçmiş de aynı kayıtta durmalı ki neyin neden başarısız olduğu görülebilsin. Ayrıca kuyruğun otomatik olarak temizlenmemesi gerekir. Otuz gün saklama, hem uyuşmazlık çözümünde hem de tekrar eden bir kalıbı fark etmede işe yarar. Panelde ölü harf sayısının sürekli artıyor olması, çoğu zaman tek bir bayinin bozuk uç noktasına işaret eder. Fiyat ve paket karşılaştırması için fiyat bölümüne göz atabilirsin.
Kendi Webhook Tekrar Deneme Politikanı Nasıl Yazarsın?
Politikanın tek sayfa olması yeterli ama dört soruyu net cevaplaması gerekir. Hangi yanıt kodları tekrar denenir? Kural olarak 408, 429 ve tüm 5xx denenir; 400, 401, 403 ve 404 denenmez, çünkü bunlar yapılandırma hatasıdır ve tekrar denemek düzeltmez. Kaç kez denenir ve hangi eğriyle? Yedi deneme ve çarpanlı bekleme çoğu iş için dengelidir.
Üçüncü soru: alıcıya ne kadar süre verilir? Uç noktanın on saniyeden fazla yanıt vermemesi gerekir; bunu aşan bir alıcı, işi arka plana atmayı öğrenmelidir. Dördüncüsü: vazgeçtikten sonra ne olur? Yönetici uyarısı, ölü harf kaydı ve elle yeniden gönderme yolu. Bu dört cevabı yazıp uç nokta dokümantasyonuna eklediğinde bayilerin de beklentisi netleşir. Sağlam bir e-pin scripti için bu doküman, kodun kendisi kadar değerlidir.
| Kontrol maddesi | Neden gerekli | Hazır sayılma ölçütü |
|---|---|---|
| Kalıcı gönderim kaydı | İzlenebilirlik ve kanıt | Her deneme loglanıyor |
| Artan bekleme + sapma | Dalga etkisini kırar | Rastgele pay uygulanıyor |
| Tekil olay kimliği | Çift işlemeyi engeller | Tekrar denemede kimlik sabit |
| Ham gövde imzası | Sahte bildirimi keser | Ayrıştırmadan önce doğrulanıyor |
| Zaman damgası penceresi | Tekrar oynatmayı bitirir | 5 dakikadan eski reddediliyor |
| Kalıcı hatada deneme yok | Boşa yükü önler | 4xx eğriden çıkarılmış |
| Ölü harf + elle gönderim | Kurtarma yolu bırakır | Panelden tek tuşla mümkün |
Gelen bildirimde iş yapmadan önce kaydet ve hemen 200 dön. Ağır işi kuyruğa bırak; böylece gönderen tarafın zaman aşımı hiç devreye girmez.
Bildirim katmanını sıfırdan yazmak zorunda değilsin
Artan bekleme, olay kimliği, imza doğrulama ve ölü harf kuyruğu Pinova'da hazır çalışır; panelden her denemeyi tek tek görürsün.
Webhook yerine düzenli sorgulama yapsam olmaz mı?
İkisi birbirinin alternatifi değil, tamamlayıcısıdır. Webhook hızlıdır, sorgulama ise güvenlik ağıdır. En sağlam kurulum webhook'la çalışır, saatlik bir mutabakat sorgusuyla eksikleri kapatır.
Alıcı 200 dönüyor ama işlemiyorsa ne yaparım?
Bu bir teslimat sorunu değil, alıcı tarafında mantık hatasıdır. Tekrar deneme bunu çözmez; mutabakat raporu ile farkı yakalayıp alıcıya bildirmen gerekir.
Bekleme eğrisini daha agresif yapsam teslimat hızlanır mı?
Hayır, genelde yavaşlatır. Yoğunluk altındaki bir alıcıya daha sık gitmek toparlanmasını geciktirir ve toplam teslimat süresini uzatır.
Olay kimliğini nasıl üretmeliyim?
Sipariş kimliği ve olay türünün birleşiminden türetilen deterministik bir değer en pratiğidir. Rastgele üretilen bir kimlik tekrar denemede değişirse koruma işlevini yitirir.
Webhook tekrar deneme stratejisi, dışarıdan bakıldığında hiç görünmeyen ama işletmenin güvenilirliğini doğrudan belirleyen bir katmandır: iyi kurulduğunda kimse varlığını fark etmez, kötü kurulduğunda her hafta bir mutabakat toplantısı doğurur. Kendi bildirim akışını bu ölçütlere göre denetlemek istersen canlı demo içindeki webhook günlüğünü açıp deneme geçmişini, imza durumunu ve ölü harf listesini kendi uç noktalarınla karşılaştırarak somut bir başlangıç yapabilirsin.