Çoğu işletme sahibi webhook konusunda şunu sanır: ödeme sağlayıcı bildirimi göndermeyi unutmuştur, dolayısıyla suçlu karşı taraftır. Destek ekranını açar, "webhook gelmiyor" yazar, üç gün bekler, cevap olarak "bizim loglarımızda 200 dönüyor" görür ve dosya kapanır. Oysa sipariş hâlâ beklemede, müşteri hâlâ WhatsApp'tan yazıyor, sen hâlâ e-pin kodunu elle gönderiyorsun. Bu döngü aylarca sürebilir çünkü kimse doğru yere bakmıyor.
Gerçek şu: webhook'ların ezici çoğunluğu sana ulaşır, senin e-pin scriptin onları sessizce yer. Bir zaman aşımı, bir güvenlik duvarı kuralı, bir imza kontrolü, bir tekrar denemede oluşan çift kayıt hatası... Bildirim kapıya kadar gelir, kapı açılmaz veya açılır ama içeride kimse kaydı almaz. Bu yazıda bir dijital ürün satış scriptinin webhook katmanını parça parça sökeceğiz; nerede kaybettiğini, nasıl kanıtlayacağını ve bir daha asla kaybetmemek için hangi mimariyi kuracağını göstereceğiz.
Webhook Gerçekten Ulaşmıyor mu, Yoksa Senin Scriptin Onu Sessizce Çöpe mi Atıyor?
İlk iş, iddiayı kanıta çevirmek. Ödeme sağlayıcısının panelindeki "gönderildi" kaydı hiçbir şey ispatlamaz; senin sunucunun eriştiği log ise her şeyi ispatlar. Doğru kurulmuş bir e-pin satış scriptinde webhook uç noktası, işi yapmadan önce ham gövdeyi diske veya veritabanına yazar. Yani imza doğru mu, sipariş var mı, tutar uyuyor mu sorularının hiçbiri sorulmadan önce kayıt düşer. Böylece "bildirim geldi ama işlenmedi" ile "bildirim hiç gelmedi" arasındaki fark bir bakışta görünür.
Sunucu erişim logu bu konuda en dürüst tanıktır. Uç nokta adresini logda arattığında hiç satır yoksa trafik sunucuya varmamıştır ve sorun ağ katmanındadır. Satır varsa ama durum kodu 403, 404, 500 veya 502 ise bildirim gelmiş, kapıda geri çevrilmiştir. En sinsi durum ise 200 dönmesine rağmen siparişin ilerlememesidir: scriptin bildirimi almış, "tamam" demiş, sonra kendi iç mantığında sessizce düşmüştür. Bu üçüncü senaryo epin yazılım projelerinde en sık görülen ve en çok zaman kaybettiren durumdur.
Sağlayıcı "Gönderdim" Diyorsa Neden Siparişin Hâlâ Beklemede?
Ödeme sağlayıcıları bildirimi gönderir ve senden hızlı bir onay bekler. Bu bekleme süresi genellikle üç ile on saniye arasındadır. Şimdi tipik bir dijital ürün satış scriptinin webhook anında neler yaptığını düşün: siparişi bulur, stoktan e-pin kodu ayırır, kodu şifre çözer, müşteriye e-posta gönderir, SMS API'sine istek atar, tedarikçi API'sinden bakiye sorgular, fatura kaydı oluşturur, Telegram'a bildirim yollar. Bu zincirde tek bir yavaş servis, örneğin cevap vermeyen bir SMTP sunucusu, tüm isteği zaman aşımına sokar.
Zaman aşımına düşen istek sağlayıcı tarafında "başarısız" görünür ve tekrar denemeye alınır. Kötü haber: senin tarafında işlemin bir kısmı çoktan yapılmıştır. Kod ayrılmış, e-posta belki gitmiş, ama sipariş durumu güncellenmemiştir. Tekrar deneme geldiğinde script aynı işi baştan yapar ve aynı müşteriye ikinci bir kod gider veya aynı sipariş iki kez faturalanır. Yani sorun sadece "ulaşmıyor" değil, ulaşan bildirimin yarım işlenmesidir. Çözüm yavaş işleri webhook isteğinden tamamen sökmektir; buna birazdan geleceğiz.
| Belirti | Sunucu Logunda Görünen | Gerçek Sebep | İlk Müdahale |
|---|---|---|---|
| Hiç kayıt yok | Uç nokta adresi logda geçmiyor | Güvenlik duvarı, IP filtresi veya yanlış adres | Sağlayıcı IP bloklarını beyaz listeye al |
| 403 / 406 | Erişim reddedildi | WAF kuralı POST gövdesini saldırı sanıyor | Uç nokta için WAF istisnası tanımla |
| 301 / 302 | Yönlendirme zinciri | www veya HTTPS yönlendirmesi POST'u düşürüyor | Kanonik adresi sağlayıcı paneline yaz |
| 504 / zaman aşımı | Yanıt 10 saniyeyi aşıyor | Webhook içinde mail, SMS, API çağrısı var | Ağır işleri kuyruğa taşı |
| 200 ama sipariş beklemede | Başarılı yanıt, işlem yok | İmza hatası veya sipariş eşleşmemesi sessizce yutuluyor | Her reddi gerekçesiyle logla |
| Çift teslimat | Aynı referans iki kez | Tekrarlı bildirimde idempotency yok | Referans üzerine tekil indeks koy |
IP Kısıtlaması, WAF ve CDN: Kendi Kalkanın Seni Vuruyor Olabilir mi?
Hosting paketine dahil gelen güvenlik modülleri, e-pin scripti gibi finansal bildirim alan sistemlerde en büyük sessiz katildir. Bir ödeme bildirimi gövdesi içinde uzun imza dizeleri, JSON blokları ve bazen Base64 parçaları taşır. Kural tabanlı bir güvenlik duvarı bunu enjeksiyon denemesi olarak yorumlayıp isteği kesebilir. Sen hiçbir şey görmezsin; sağlayıcı 403 görür, birkaç kez dener, vazgeçer.
İkinci klasik tuzak önbellek ve yönlendirme katmanıdır. Alan adın bir CDN arkasındaysa ve uç noktan için "önbelleğe alma" kuralı yoksa, POST isteği beklenmedik şekilde işlenebilir. Daha da yaygını yönlendirme sorunudur: sağlayıcı paneline http ile başlayan veya www içermeyen bir adres yazmışsın, sunucu bunu kanonik adrese yönlendiriyor, yönlendirme sırasında POST gövdesi kayboluyor ve uç noktana boş bir GET isteği düşüyor. Script gövdeyi bulamayınca sessizce çıkıyor. Sağlayıcı paneline yazdığın adres, sunucunun tek ve son adresi olmalı; hiçbir yönlendirmeye girmemeli.
Ulaşmayan Webhook Vakalarının Gerçek Dağılımı
- Kendi sunucunda kesilenler (WAF, IP, yönlendirme) 45%
- Zaman aşımı ve yavaş işlem 25%
- İmza veya eşleşme hatasıyla sessiz ret 20%
- Gerçekten sağlayıcı kaynaklı 10%
İmza Doğrulama Neden Doğru Ödemeleri de Reddeder?
İmza doğrulaması olmazsa olmazdır; onsuz herkes sahte ödeme bildirimi yazıp senden bedava e-pin alır. Ama yanlış uygulanmış imza kontrolü geçerli ödemeleri de çöpe atar. En sık üç hata şudur. Birincisi, gövdeyi çözümleyip yeniden birleştirerek imza hesaplamak: sıralama veya boşluk değişince özet tutmaz. İmza her zaman ham istek gövdesi üzerinden hesaplanmalıdır. İkincisi, anahtarın test ile canlı ortam arasında karışmasıdır; canlıya geçerken sandbox anahtarı yerinde kalır ve tüm bildirimler reddedilir.
Üçüncü hata daha incedir: karakter kodlaması. Sipariş açıklamasında Türkçe karakter varsa ve senin scriptin gövdeyi farklı bir karakter setinde okuyorsa, bayt dizisi değişir ve imza asla tutmaz. Bu yüzden iyi bir e-pin satış yazılımı imzayı hesaplamadan önce gövdeye hiç dokunmaz, doğrudan okur. Ayrıca reddettiği her bildirimi "neden reddettim" gerekçesiyle kaydeder. Gerekçesiz reddetmek, sorunu görünmez yapmaktır.
Tek Gerçek Çözüm: Webhook'u Kuyruğa Yaz, İşi Sonra Yap
Dayanıklı mimari şaşırtıcı derecede basittir ve iki cümleyle özetlenir. Webhook uç noktası sadece üç şey yapar: ham gövdeyi kaydeder, tekil referansla çift kaydı engeller, saniyenin altında 200 döner. Teslimat, e-posta, SMS, fatura ve bildirim işleri ise bir işçi süreci veya dakika başı çalışan bir görev tarafından kuyruktan çekilerek yapılır.
Bu ayrımın kazandırdıkları şunlardır: SMTP sunucusu düşse bile ödeme kaydı kaybolmaz; tedarikçi API'si yavaşlasa bile sağlayıcı zaman aşımı görmez; tekrarlı bildirim geldiğinde tekil indeks onu reddeder ve çift teslimat imkânsız hâle gelir. Kuyruktaki bir iş başarısız olursa artan bekleme süreleriyle yeniden denenir, üç denemeden sonra insan müdahalesi için işaretlenir. Böylece sistem hata yapmaz hâle gelmez; hatadan kendi kendine dönebilir hâle gelir. Pinova'da webhook katmanı tam olarak bu ilkeyle kurulur; bildirim ile teslimat aynı isteğin içinde asla birleşmez.
Uç noktana geçici olarak sadece ham gövdeyi kaydedip 200 dönen bir satır ekle. Bir test ödemesi yap. Kayıt düşüyorsa sorun ağda değil, senin işleme mantığındadır ve aramayı doğru yerde daraltmış olursun.
Webhook'a Hiç Güvenmemek: Yoklama Ağını Kurmak
Olgun bir dijital ürün satış scripti webhook'u tek gerçek kaynak saymaz. Çünkü bildirim kaybı ihtimali asla sıfırlanmaz: sunucun bakım için kapalı olabilir, sağlayıcı tarafında bir arıza yaşanabilir, DNS geçici olarak çözülmeyebilir. Bu yüzden ikinci bir ağ gerekir: beklemede kalan siparişleri belirli aralıklarla sağlayıcının sorgu servisine sormak.
Pratik kurgu şöyledir. Beş dakikadan uzun süre "ödeme bekleniyor" durumunda kalan her sipariş için otomatik bir durum sorgusu yapılır. Sağlayıcı "ödendi" diyorsa sipariş, webhook hiç gelmemiş olsa bile teslimata alınır. Aynı işlemin iki kez teslim edilmemesi için tekil referans kilidi devreye girer. Bu yaklaşımın güzelliği, bir işletme sahibinin gece üçte gelen "param gitti kod gelmedi" mesajlarından tamamen kurtulmasıdır. Webhook hız verir, yoklama güvence verir; ikisi birlikte çalıştığında kalıcı kayıp pratikte ortadan kalkar. Sistemin bu davranışını özellikler bölümünde madde madde görebilirsin.
| Kontrol | Nasıl Doğrularsın | Geçti Sayılma Ölçütü |
|---|---|---|
| Uç nokta adresi kanonik | Adrese POST at, yönlendirme sayısına bak | Sıfır yönlendirme, doğrudan 200 |
| Ham gövde kaydı açık | Son 24 saatin bildirim kayıtlarını listele | Her bildirim, reddedilse bile kayıtlı |
| Yanıt süresi | Uç nokta yanıt süresini ölç | Sürekli 1 saniyenin altında |
| Çift teslimat koruması | Aynı bildirimi elle iki kez gönder | İkinci istek işlem yapmadan 200 döner |
| İmza reddi gerekçeli | Bilerek bozuk imzalı istek at | Kayıtta ret nedeni açıkça yazıyor |
| Yoklama görevi çalışıyor | Görev geçmişini incele | Beklemede takılan sipariş 10 dakikada çözülüyor |
| Uyarı mekanizması | Bildirim akışını kasten kes | 15 dakika içinde sana uyarı düşüyor |
Webhook kaybını mimariyle bitir, destekle değil
Kuyruk tabanlı bildirim işleme, idempotent teslimat ve otomatik yoklama ağı Pinova'da hazır gelir. Kendi e-pin satış scriptini sıfırdan sağlamlaştırmak yerine test edilmiş bir temelden başla.
Webhook geldi ama sipariş ilerlemiyorsa nereden başlamalıyım?
Ham gövde kaydına bak. Kayıt varsa sorun ağda değil işleme mantığındadır: imza, sipariş eşleşmesi veya tutar kontrolü sessizce reddediyordur. Her reddi gerekçesiyle loglamak bu aramayı dakikalara indirir.
Ödeme sağlayıcısının IP adreslerini beyaz listeye almak zorunlu mu?
Güvenlik duvarı veya sunucu düzeyinde bir filtre kullanıyorsan evet. Aksi hâlde bildirimler sana ulaşmadan reddedilir. IP listeleri değişebildiği için ayrıca imza doğrulamasını da mutlaka açık tut.
Webhook yerine sadece yoklama kullansam olmaz mı?
Olur ama teslimat gecikir ve sunucuya gereksiz yük biner. Doğru kurgu ikisini birlikte kullanmaktır: webhook anında teslim eder, yoklama kaçanları yakalar. Tekil referans kilidi çift teslimatı engeller.
Aynı bildirim iki kez gelirse müşteriye iki kod gider mi?
Idempotency yoksa gider. Sağlayıcı referansı üzerine tekil indeks koyup işlemi tek seferlik hâle getirmelisin. İkinci istek hiçbir iş yapmadan başarılı yanıt döndürmeli.
Webhook sorunları teknik bir kaza gibi görünür ama aslında bir mimari tercihin sonucudur: bildirimi almakla işi yapmayı aynı saniyeye sıkıştırdığın an kayıp kaçınılmaz olur. Bu ayrımı doğru kurmuş bir sistemin nasıl davrandığını okumak yerine kendi gözünle görmek istersen canlı demo üzerinden bildirim kayıtlarını, kuyruk ekranını ve otomatik teslimat akışını inceleyebilir, ardından fiyat bölümünde sana uygun paketi seçebilirsin.