- Katılım
- 21 May 2023
- Mesajlar
- 539
- Tepki
- 17
- Puan
- 18
Sunucunuz birkaç dakikalığına yeniden başlarken bir ödeme sağlayıcısının gönderdiği webhook isteği tam o ara denk gelirse, o olayı hiç almamış olabilirsiniz. Sorun sizin kodunuzda değil, zamanlamada; ama sonuç aynı: bir sipariş durumu güncellenmemiş, bir stok düşürülmemiş kalır.
Bu yazı, webhook gönderen tarafın başarısız teslimatları nasıl yeniden denediğini ve alıcı tarafın bu tekrarları nasıl güvenle karşılaması gerektiğini gösteriyor.
Stripe'ın otomatik yeniden deneme davranışı
Stripe'ın resmî webhook belgesine göre canlı modda başarısız bir teslimat için üstel geri çekilme (exponential backoff) ile en fazla üç gün boyunca yeniden deneme yapılıyor. Sandbox/test modunda ise birkaç saat içinde üç deneme yapılıyor. Belge, hedef endpoint devre dışı bırakılır veya silinirse o olay için gelecekteki denemelerin durdurulduğunu, ama endpoint yeniden etkinleştirilirse kalan denemelerin devam edebileceğini de belirtiyor.
Bu davranış, endpoint'inizin kısa süreli bir kesinti yaşaması durumunda otomatik olarak bir tolerans payı sağlıyor; sizin ayrı bir yeniden deneme mekanizması kurmanıza gerek kalmadan, gönderen taraf bunu zaten üstleniyor. Bu da başta anlattığımız senaryoyu, yani sunucunun birkaç dakikalığına yeniden başladığı anı, çoğu zaman kayıpsız atlatmanızı sağlıyor; asıl risk, kesintinin otomatik deneme penceresinden daha uzun sürmesi.
Manuel yeniden gönderme farklı bir yol
Aynı belgeye göre otomatik denemelerin dışında iki manuel yol daha var: panelden tek bir olayı yeniden göndermek (olay oluşturulduktan sonra 15 güne kadar çalışıyor) veya komut satırı aracıyla yeniden göndermek (30 güne kadar çalışıyor). Belge, manuel yeniden göndermenin otomatik yeniden deneme davranışını iptal etmediğini özellikle vurguluyor; yani bir olayı elle tekrar gönderseniz bile, otomatik denemeler ayrı bir çizgide devam edebiliyor.
Bu da doğal olarak aynı olayın birden fazla kez, farklı kanallardan gelebileceği anlamına geliyor; alıcı tarafın buna hazırlıklı olması gerekiyor.
Stripe'ın belgesi ayrıca olayların üretildikleri sırayla teslim edilmesinin garanti edilmediğini de belirtiyor. Bir abonelik oluşturulduğunda birbiriyle ilişkili birden fazla olay (müşteri oluşturma, fatura oluşturma, fatura ödeme gibi) art arda üretilebiliyor; ama bunların hangi sırayla ulaşacağı garanti değil. Belge, hedef sistemin olayları yalnızca belirli bir sırada bekleyecek şekilde tasarlanmaması gerektiğini, eksik nesnelerin gerekirse API üzerinden ayrıca çekilebileceğini öneriyor.
GitHub'ın endpoint tarafına önerdiği
GitHub'ın webhook en iyi uygulamalar belgesine göre "sunucunuz, bir webhook teslimatını aldıktan sonra 10 saniye içinde bir 2XX yanıtıyla cevap vermeli." Bu süre sınırı, ağır bir iş yükünü (örneğin bir veritabanı güncellemesini) doğrudan istek işleyicisinin içinde yapmak yerine, isteği hızlıca onaylayıp asıl işi arka planda kuyruğa almanın neden tercih edildiğini açıklıyor.
Aynı belge, tekrarlanan teslimatları ayırt etmek için benzersiz bir teslimat kimliğinin (X-GitHub-Delivery başlığı) kullanılabileceğini belirtiyor; bir teslimat yeniden gönderildiğinde bu kimlik orijinal teslimatla aynı kalıyor. Bu, alıcı tarafın "bu olayı daha önce işledim mi" sorusunu güvenilir şekilde cevaplamasının anahtarı.
İdempotens: aynı olayı iki kez işlememek
Yeniden deneme mekanizması var olduğu sürece, aynı olayın en az bir kez, bazen birden fazla kez ulaşacağını varsaymak gerekiyor. Bunun pratik çözümü, her olayın benzersiz kimliğini (Stripe'ta olay kimliği, GitHub'da teslimat kimliği) işlemeden önce kontrol etmek: daha önce işlenmiş bir kimlik tekrar geldiğinde, işlemi tekrarlamak yerine sessizce 2XX döndürmek yeterli.
- Hızlı yanıt verin: Ağır işi arka plana alın, isteği önce onaylayın.
- Olay kimliğini saklayın: İşlenmiş kimlikleri bir tabloda tutup tekrarları burada eleyin.
- Sıralamaya güvenmeyin: Olaylar üretildikleri sırayla ulaşacak diye bir garanti yok; eksik nesneleri gerekirse API'den ayrıca çekin.
- Başarısız işleneni loglayın: Otomatik yeniden deneme süresi dolduktan sonra elinizde manuel araştırma için bir kayıt kalsın.
Bu tür bir entegrasyonun "çalışıyor" görünmesi yetmez; gerçekten test edilebilir ve doğrulanabilir olması gerekir. "Çalışsın" yerine kabul kriteri yazımız tam olarak bu noktaya, bir entegrasyonun teslim edilirken hangi ölçütlerle test edilebilir hale getirileceğine değiniyor.
CI/CD tarafında benzer bir tuzak
Webhook işleyicinizi bir CI/CD hattı üzerinden dağıtıyorsanız, dağıtımın kendisinde de benzer bir önbellek/tekrar sorunu yaşanabilir. derleme önbelleğinin eski dosyayı sunmasını ele aldığımız yazı, dağıtılan kodun beklenenle aynı olduğundan emin olmanın neden ayrı bir kontrol gerektirdiğini gösteriyor. Bu entegrasyonu bir müşteriye teslim ediyorsanız, kaynak kodun ve erişim bilgilerinin devrini de netleştirmek gerekir; yazılım tesliminde kaynak kod ve erişimler nasıl devredilir yazımız bu süreci ayrıca ele alıyor.
Püf nokta' Alıntı:
Özetle
Webhook gönderen taraf (Stripe, GitHub gibi) başarısız teslimatları belirli bir süre boyunca otomatik olarak yeniden dener; alıcı tarafın görevi hızlı yanıt vermek ve aynı olayı birden fazla kez işlemeyecek şekilde idempotens kurmak. Bu iki parça bir araya gelmeden, "webhook'um bazen olayları kaçırıyor" şikâyeti genelde tekrar eder.
Sizin entegrasyonunuz aynı olayı iki kez aldığında ne oluyor, hiç test ettiniz mi?
Güncelleme: 24 Ağustos 2026.
Dijital Dünyanıza Yön Veren Pusula
