Webhook Nedir ve Nasıl Çalışır?

Kısa yanıt

Webhook, bir sistemde belirli bir olay gerçekleştiğinde bu bilgiyi otomatik olarak başka bir sunucuya ileten bir bildirim yöntemidir. Alıcı sistem veri çekmek için sürekli sorgu göndermez; gönderen taraf olay anında bir HTTP isteğiyle veriyi kendisi iletir. E-ticarette ödeme onayı, CRM’de yeni müşteri kaydı veya GitHub’da kod gönderimi gibi anlık tetikleyiciler,

webhook sayesinde başka bir yazılıma gecikmesiz ulaşır..

Webhook nedir ve nasıl çalışır?

Webhook kavramı “web” ve “hook” (kanca) kelimelerinin birleşiminden gelir ve bir yazılımın belirli bir olayı başka bir sisteme otomatik bildirmesini sağlayan HTTP tabanlı bir mekanizmayı tanımlar. Gönderen taraf, önceden tanımlanmış bir URL’ye (uç nokta) olay gerçekleştiğinde bir JSON yükü gönderir; bu yük genellikle olayın türünü, zaman damgasını ve ilgili kaydın kimliğini içerir. Alıcı sunucu isteği aldığında kendi iş mantığını çalıştırır: bir veritabanı kaydı oluşturabilir, bir e-posta tetikleyebilir veya başka bir sisteme veri aktarabilir.

Kurulumu iki yönlü bir kayıt gerektirir. Webhook’u kullanan taraf önce alıcı sistemde bir uç nokta tanımlar, sonra gönderen sistemin ayar panelinde bu adresi hangi olaylarda tetikleneceğini belirterek kaydeder. Stripe’ta bir ödeme tamamlandığında, GitHub’da bir pull request birleştirildiğinde veya bir e-ticaret platformunda sipariş durumu değiştiğinde, kayıtlı her uç noktaya otomatik olarak istek gönderilir.

Webhook ile API arasındaki fark nedir?

API ve webhook çoğu zaman birbirine karıştırılır, oysa veri akışının yönü temelde farklıdır. Klasik bir API çağrısında istemci taraf veriyi talep eder; güncel veriyi görmek için düzenli aralıklarla sorgu göndermesi (polling) gerekir ve bu da gecikme yaratır. Webhook’ta ise bu yön tersine döner: olay gerçekleştiği anda gönderen taraf veriyi kendisi iletir, alıcı hiçbir sorgu göndermeden bildirimi alır.

Bu fark, sunucu kaynaklarının kullanımını da doğrudan etkiler. Dakikada onlarca kez “değişiklik var mı” diye soran bir entegrasyon, iki tarafın sunucusunu da gereksiz yere yorar; webhook ise yalnızca gerçek bir olay olduğunda çalışır. Gerçek zamanlı bildirim gerektiren senaryolarda webhook, API’ye kıyasla genellikle daha verimli bir seçenektir.

Bir webhook isteği hangi adımlardan geçer?

Bir webhook isteğinin yaşam döngüsü birkaç net adıma ayrılır. Önce alıcı sistemde bir uç nokta oluşturulur ve bu adres, gelen istekleri işleyebilecek şekilde kodlanır. Ardından gönderen platformun ayar panelinde bu URL kayıt edilir ve hangi olaylarda tetikleneceği seçilir; örneğin “sipariş tamamlandı” veya “kullanıcı kaydoldu” gibi belirli olay türleri işaretlenir.

Olay gerçekleştiğinde gönderen sistem genellikle JSON formatında bir HTTP POST isteği oluşturur ve bunu kayıtlı adrese iletir. Alıcı sunucu isteği aldığında önce kimlik doğrulamasını kontrol eder, sonra yükü işler ve son olarak gönderen tarafa 200 durum koduyla “istek başarıyla alındı” yanıtını döner. Bu yanıt gelmezse gönderen sistem, isteği belirli aralıklarla yeniden göndermeyi dener.

Webhook güvenliği: imza doğrulama ve HTTPS neden şart?

Bir webhook uç noktası tanım olarak herkese açık bir adrestir; bu durum ciddi bir güvenlik riski taşır, çünkü adresi öğrenen biri sahte bir istek göndererek sisteme yanlış veri enjekte edebilir. Bu riski azaltmak için gönderen platformların çoğu, her isteğe gizli bir anahtarla üretilmiş dijital bir imza ekler; alıcı sunucu bu imzayı kendi tarafında yeniden hesaplayıp karşılaştırarak isteğin gerçekten beklenen kaynaktan geldiğini doğrular.

İmza doğrulamasında kullanılan gizli anahtar kaynak koduna gömülmemeli, bir sır yöneticisinde ya da ortam değişkeninde saklanmalıdır; bu anahtarın bir depoya yanlışlıkla eklenmesi, GitHub’da API anahtarı sızıntısı ne yapmalı rehberimizde ele aldığımız sızıntı senaryosuyla aynı aciliyeti taşır. HTTPS kullanımı da aynı derecede kritiktir, çünkü şifrelenmemiş bir bağlantı üzerinden giden yük, araya giren biri tarafından okunabilir veya değiştirilebilir. Bu iki önlem birlikte uygulanmadığında webhook, kolay bir saldırı yüzeyine dönüşür.

Webhook’lar işletmeler için hangi süreçlerde kullanılır?

Ödeme sistemleri, webhook’un en yaygın kullanıldığı alanlardan biridir; PayTR, Iyzico veya Stripe gibi sağlayıcılar bir ödeme onaylandığında ya da iade edildiğinde mağaza sunucusuna anlık bildirim gönderir, böylece sipariş durumu müşteri ekranına saniyeler içinde yansır. E-ticaret platformlarında kargo takip numarası oluştuğunda veya stok seviyesi kritik eşiğe düştüğünde tetiklenen webhook’lar, API entegrasyonu rehberimizde ele aldığımız ERP senkronizasyonunun temel yapı taşlarından biridir.

CRM sistemlerinde de webhook yaygın bir kullanım alanı bulur: bir form doldurulduğunda, bir anlaşma aşaması değiştiğinde veya bir müşteri aboneliğini iptal ettiğinde, ilgili bilgi anında satış ekibinin kullandığı panele veya bir Slack kanalına iletilebilir. Pazarlama otomasyonu araçları, kullanıcı bir e-postayı açtığında veya bir bağlantıya tıkladığında tetiklenen webhook’larla segmentasyon kararlarını gerçek zamanlı güncelleyebilir.

Webhook başarısız olduğunda ne olur?

Bir webhook isteği her zaman ilk denemede başarıyla ulaşmaz; alıcı sunucu o anda bakımda olabilir, ağ bağlantısı kesilebilir veya sunucu beklenmedik bir hata döndürebilir. Çoğu sağlayıcı bu durumu öngörür ve başarısız bir isteği artan aralıklarla (örneğin birkaç saniye, sonra birkaç dakika, sonra birkaç saat) yeniden göndermeyi birkaç kez dener; buna üstel geri çekilme (exponential backoff) denir.

Tüm yeniden denemeler tükendiğinde istek genellikle “başarısız” olarak işaretlenir ve bazı sistemlerde ayrı bir kuyruğa (dead letter queue) taşınır. Ciddi bir webhook entegrasyonu kuran ekiplerin, başarısız istekleri izleyen bir panel ve bu durumlarda ekibe anlık uyarı gönderen bir mekanizma kurması önerilir; günlerce fark edilmeyen bir kesinti, muhasebe veya stok verisinde sessizce büyüyen bir tutarsızlığa dönüşebilir.

Webhook mi, periyodik sorgu (polling) mi?

Her entegrasyon webhook’a uygun değildir. Alıcı sistemin webhook almaya hazır, herkese açık bir sunucusu yoksa veya karşı taraf webhook desteği sunmuyorsa, periyodik sorgu tek seçenek olarak kalır; bu durumda alıcı sistem belirli aralıklarla “yeni bir şey var mı” diye sorar ve belli bir gecikme kaçınılmaz hale gelir.

Gerçek zamanlı bildirim gerektiren, sık değişen ve anlık tepki beklenen süreçlerde webhook neredeyse her zaman daha isabetli bir seçimdir. Günde bir kez çalışacak bir rapor veya nadiren değişen bir veri kümesi için basit bir zamanlanmış görev, webhook altyapısı kurmanın getirdiği ek bakım yüküne değmeyebilir.

Zapier, Make ve n8n gibi araçlarda webhook nasıl kullanılır?

Kod yazmadan otomasyon kurmak isteyen ekipler için Zapier, Make ve n8n gibi platformlar webhook’u görsel bir arayüzün arkasına gizler. Bu araçlarda bir “webhook tetikleyicisi” eklendiğinde platform otomatik bir URL üretir; bu adres herhangi bir sisteme (özel bir form, bir ödeme sağlayıcısı veya bir mobil uygulama) kopyalanıp olay tetikleyicisi olarak tanımlanabilir.

Webhook URL’si tetiklendiğinde platform gelen veriyi okur ve kullanıcının önceden kurduğu adımları (bir e-posta göndermek, bir satırı tabloya eklemek, bir Slack mesajı yollamak) sırayla çalıştırır. Bu yaklaşım, özel kod yazmadan karmaşık entegrasyonlar kurmak isteyen küçük ekipler için hızlı bir başlangıç noktasıdır; hacim arttıkça veya özel iş mantığı gerektiğinde özel yazılım projeleri kapsamında kurulan doğrudan entegrasyonlar daha sürdürülebilir hale gelir.

Webhook kurarken sık yapılan hatalar

En sık rastlanan hata, gelen isteğin imzasını hiç doğrulamadan doğrudan işlemektir; bu, o adresi bulan herkesin sahte veri gönderebilmesi anlamına gelir. İkinci yaygın hata, alıcı uç noktanın yanıt süresini uzun tutmaktır: webhook isteğini aldıktan sonra ağır bir işlemi senkron olarak çalıştırıp yanıtı geciktirmek, gönderen tarafın isteği “başarısız” sayıp tekrar göndermesine ve aynı olayın birden fazla kez işlenmesine yol açabilir.

Üçüncü hata, aynı olayın birden fazla kez işlenme ihtimalini hiç hesaba katmamaktır. Ağ kesintileri nedeniyle aynı webhook isteği teorik olarak iki kez ulaşabilir; her isteğe eşlik eden tekil bir kimlik (idempotency key) kontrol edilmeli ve aynı kimlikle gelen ikinci istek sessizce yok sayılmalıdır.

Sonraki adım

Webhook, iki sistem arasında gecikmesiz ve verimli bir bildirim köprüsü kurmanın en pratik yollarından biridir; asıl değeri de tam burada ortaya çıkar, çünkü periyodik sorgulamanın getirdiği gecikmeyi ve sunucu yükünü ortadan kaldırır. Kurulumda imza doğrulamasını atlamamak, yanıt süresini kısa tutmak ve mükerrer istekleri idempotency anahtarıyla engellemek, bu basit mekanizmayı üretim ortamında güvenilir kılan üç temel adımdır. GitHub’ın resmi belgelerinde webhook’ların olay bazlı nasıl tetiklendiği ve hangi veri yapısını kullandığı ayrıntılı şekilde açıklanır; teknik referans için GitHub’ın webhook belgelerine göz atabilirsiniz.

Sisteminizin entegrasyon ve otomasyon mimarisini uçtan uca gözden geçirmek isterseniz grup şirketimiz Web Tasarım Ofisi özel yazılım projelerinde bu konuda da destek veriyor. Kurumsal yazılım ihtiyaçlarınızı birlikte değerlendirmek için özel yazılım hizmetimizi inceleyebilir ya da bizimle iletişime geçebilirsiniz.