Başka bir servisin API'sini test etmek çoğu zaman proxy ile başlar — giden yol hızlıca ve sorunsuz ayarlanır. Sonra aynı sağlayıcıdan bir webhook gelir — siparişin ödendiğini, numaranın SMS aldığını ya da görevin tamamlandığını bildiren geri çağrı — ve veri bir türlü ulaşmaz. Proxy'nin bu işle neden ilgisi olmadığını, kesintinin nereden kaynaklandığını ve geri çağrı alımını giden kanaldan bağımsız hâle getirmeyi adım adım inceleyelim.

Proxy giden yolu değiştirir, giriş kapısı açmaz

Proxy sunucusu, istemciniz ile uzaktaki API arasında yalnızca giden hatta yer alır: bağlantıyı siz başlatırsınız, o da geri adresi ve isteğin göründüğü IP'yi değiştirir. Bundan sonra olan her şey, sizin zaten açtığınız bağlantıya verilen yanıttır. Webhook ise tam tersi çalışır: başlatan siz değil, sağlayıcıdır. Sağlayıcı, panelde ya da istek parametrelerinde önceden kaydettiğiniz URL'ye yeni bir bağlantı açar ve bu bağlantının, kısa süre önce API'ye giderken kullandığınız kanalla hiçbir ilgisi yoktur.

Tipik karışıklık buradan doğar: giden kanalı değiştirdiniz ve geri çağrıların artık farklı akacağını düşündünüz. Oysa gelen isteğin yolunu yalnızca alıcı URL'sinin nereyi gösterdiği ve bu adresin dışarıdan görünüp görünmediği belirler; giden isteklerinizin hangi kanaldan çıktığı belirlemez.

Geri çağrı neden ulaşmaz

Kaybolan bir webhook'un nedenleri azdır ve hepsi göndericide değil, alıcı tarafındadır. Makine, port yönlendirmesi yapılmamış bir ev ya da ofis yönlendiricisinin NAT'ı arkasındadır — dışarıdan bakınca adresi sanki yoktur. Yerel geliştirme adresi internetten hiçbir şekilde çözümlenmez. Kayıtlı URL, yalnızca kurumsal ağdan görünen bir iç sunucuyu gösterir. TLS sertifikasının süresi dolmuştur ya da başka bir alan adı için düzenlenmiştir ve el sıkışma, istek gövdesi iletilmeden kesilir. Sunucu 2xx dışında bir kodla yanıt verir — çoğu sağlayıcı birkaç başarısız denemeden sonra yeniden teslimatı durdurur.

Ayrı bir neden de sağlayıcının kendi allowlist'idir: altyapı değişmiş, kayıt güncellenmemiştir ve çağrılar arayüzde hiçbir hata görünmeden sessizce kaybolur.

Geri çağrılar doğru şekilde nasıl alınır

Geri çağrı alıcısı; açık bir porta ve geçerli bir TLS sertifikasına sahip, herkese açık bir adres olmalıdır — sağlayıcının sizin tarafınızda proxy ya da tünel olmadan doğrudan ulaşabileceği bir alan adı veya IP. Bu gereksinim, aynı API'ye giden isteklerde hangi kanalı kullandığınızla kesişmez.

Doğru alım mimarisi iki işi birbirinden ayırır: alındığını hızlıca onaylamak ve veriyi acele etmeden işlemek. Girişte, ham istek gövdesini kuyruğa kaydeden ve iş mantığını beklemeden hemen 200 ile yanıt veren hafif bir işleyici bulunur. İşleme ise kuyruktan, ayrı bir süreç tarafından eşzamansız olarak yapılır. Bu, sağlayıcı tarafındaki zaman aşımlarına karşı koruma sağlar: işleme saniyeler sürerken yanıt sınırı saniyenin kesirleriyse, eşzamanlı şema herhangi bir yoğunlukta er ya da geç olayları kaybetmeye başlar.

Herkese açık bir adres edinmek mümkün değilse — kapalı devre, test ortamı, alan adı olmayan geçici ortam — push yerine polling kullanın: bu tür API'lerin çoğu, durum ya da olay listesi sorgulamak için paralel bir uç nokta sunar. Bu uç noktayı belirli aralıklarla sorgulayın. Olayın alınma gecikmesi saniyelerden sorgu aralığına çıkar, ancak herkese açık erişim gereksinimi tamamen ortadan kalkar.

Teslimatın kontrolü

Kontrol tek bir günlükle değil, birbirinden bağımsız iki günlükle yapılır. Birincisi, sağlayıcının panelindeki teslimat kaydıdır: denemeler, yanıt kodları ve süreler orada görünür. İkincisi, kendi alıcınızın günlüğüdür: isteğin gerçekten kodunuza ulaştığının, yük dengeleyici ya da CDN tarafından yakalanıp gövdeyi iletmeden kendi başına 200 ile yanıtlanmadığının kanıtı. Başkasının arayüzünde "teslim edildi" durumu görünüp kendi kuyruğunuzda karşılığı yoksa, bu entegrasyonun çalıştığını kabul etmek için bir neden değil, araya giren bir yerde kopukluk olduğunun işaretidir.

İmzayı da kontrol etmekte fayda var: webhook HMAC anahtarıyla imzalanıyorsa ve gizli anahtar rotasyondan sonra eskimişse, sunucu geçerli olayları sessizce sahte diye reddeder — dışarıdan bakınca bu "gelmiyor" gibi görünür.

Proxy yine de nerede gerekli

Proxy, aynı yapının giden hattında hâlâ işe yarar. Push yerine polling'e geçtiyseniz her sorgu API'ye giden bir istektir ve başka bir sunucuya giden her trafik gibi dağıtılabilir: coğrafyaya, sıklığa göre, hız sınırında IP rotasyonuyla. Bir diğer senaryo, platformun belirli bir ülke tarafından ne gördüğünü doğrulamaktır: geri çağrı sağlayıcının coğrafyaya özgü mantığına bağlıysa, bunu varsayılan veri merkezi adresi yerine uygun bir coğrafyadan kontrol etmek daha kolaydır.

Sıkça Sorulan Sorular

Webhook'lar proxy sunucusu üzerinden alınabilir mi?

Sağlayıcının alıcınıza doğrudan ulaşabilmesi gerekir ve giden istekler için kullandığınız kanal bu zincirde yer almaz. Sunucunun gerçek adresini gizlemek gerekiyorsa, önüne ters proxy (reverse proxy) konur — bu farklı bir roldür, başka bir servisin API'sine yapılan istemci istekleri için kullanılan giden proxy ile karıştırmayın.

Sağlayıcının panelinde "teslim edildi" yazıyor ama veri yok, neden?

"Teslim edildi" durumu, sağlayıcının adresinizden 2xx yanıtı aldığı anlamına gelir — yanıtı yük dengeleyici, CDN ya da aynı alan adındaki başka bir servis vermiş olabilir ve gövdeyi kuyruğa iletmemiş olabilir. Yalnızca başkasının arayüzündeki duruma güvenmeyin; sağlayıcının günlüğünü kendi alıcınızın günlüğüyle karşılaştırın.

Herkese açık bir adres edinmek mümkün değilse ne yapmalı?

Polling'e geçin: push bildirimini beklemek yerine durum uç noktasını belirli aralıklarla sorgulayın. Olayın alınma gecikmesi artar, ancak makinenin herkese açık erişilebilir olması gereksinimi tamamen ortadan kalkar.

Yapının giden kısmı için — sağlayıcının API'sini sorgulamak ya da mantığı istediğiniz ülke tarafından kontrol etmek için — proxy kataloğundaki özel ya da rotasyonlu bir kanal uygundur. Kurulum için API ile IP rotasyonu yazısına, kanal metrikleri için ise proxy kalitesi nasıl kontrol edilir materyaline bakın.