Webhook, bir olay gerçekleştiğinde kaynak sistemin sizin adresinize bildirim göndermesidir. Bu rehberde API poll etmeden entegrasyon kurmak isteyen ekipler için farkları, güvenlik ve yeniden deneme kararlarını netleştiriyoruz.
Farklı yazılımlarınız sipariş, ödeme veya stok gibi olayları birbirine aktarmak zorunda kaldığında sürekli “çekme” (polling) yapmak hem gecikme hem de gereksiz trafik üretir. Webhook nedir sorusu, tam da bu yükü azaltmak isteyen ekipler için kritik bir başlangıç noktasıdır: bir olay gerçekleştiğinde kaynak sistem sizin belirlediğiniz adrese anında HTTP bildirimi gönderir.
Bu rehberde webhook’u API’den ayıran farkları, güvenlik ve yeniden deneme kararlarını ve işletmenizde ne zaman mantıklı olduğunu sade bir çerçevede ele alıyoruz. Amaç tanım ezberlemek değil; entegrasyon mimarinizde doğru aracı seçmenize yardımcı olmak.
Webhook nedir?
Webhook, bir uygulamada belirli bir olay olduğunda başka bir uygulamanın URL’sine otomatik HTTP isteği (genellikle POST) gönderen mekanizmadır. Karşı taraf sürekli sormaz; kaynak sistem “olay oldu” diye haber verir.
Pratikte webhook bir geri arama adresi gibidir. Örneğin ödeme sağlayıcısı başarılı tahsilat olduğunda sizin sipariş sisteminize JSON gövdeli bir istek atar. Siz de bu isteği alıp sipariş durumunu güncellersiniz.
Webhook’un değeri, gecikmenin düşük kalması ve gereksiz API çağrılarının azalmasıdır. Özellikle olay anı önemli olan süreçlerde (ödeme onayı, kargo durum değişimi, form gönderimi) bu model doğal bir tercihtir.
Webhook ile API arasındaki fark
API ve webhook çoğu projede birlikte çalışır; biri diğerinin yerine her durumda geçmez. Temel ayrım yön ve zamanlamadır.
| Ölçüt | API (polling / istek) | Webhook |
|---|---|---|
| İletişim yönü | Siz kaynak sisteme sorarsınız | Kaynak sistem size bildirir |
| Zamanlama | Sizin belirlediğiniz aralıkta | Olay anında veya kısa gecikmeyle |
| Trafik | Boş cevaplar da üretebilir | Yalnızca olay olduğunda istek gelir |
| Kontrol | Ne zaman ve neyi çekeceğinizi siz yönetirsiniz | Kaynak sistemin teslimat politikasına bağımlısınız |
| Uygun senaryo | Toplu senkron, rapor, geçmiş veri | Anlık olay, durum değişimi, tetikleyici akış |
API hâlâ listeleri çekmek, geçmiş kayıtları sorgulamak veya webhook kaçırıldığında telafi etmek için gerekir. Webhook ise “şimdi oldu” bilgisini taşıyan olay kanalıdır. Bu yüzden “API mi webhook mu?” sorusu çoğu zaman “hangisini nerede kullanmalıyız?” haline gelir.
Webhook ne zaman kullanılır?
Aşağıdaki koşullar bir araya geldiğinde webhook genelde doğru tercihtir:
- Olayın anında veya kısa sürede işlenmesi iş sonucunu etkiliyorsa (ödeme, stok rezervasyonu, abonelik iptali).
- Kaynak sistem webhook destekliyorsa ve olay kataloğu ihtiyaçlarınızı karşılıyorsa.
- Karşı uçta güvenli ve erişilebilir bir HTTPS endpoint sunabiliyorsanız.
- Aynı veriyi sık aralıklarla poll etmek maliyet veya kota baskısı yaratıyorsa.
Webhook her senaryoya uymaz. Kaynak sistem olay garantisi vermiyorsa, ağınız dışarıya kapalıysa veya toplu tarihsel senkron ihtiyacınız varsa API tabanlı çekme veya kuyruklu mimari daha sağlıklıdır. Entegrasyon kararını tek başına teknoloji değil; iş süreci ve hata toleransı belirler.
Kapsamlı bir entegrasyon planı hazırlarken yazılım yol haritası içinde webhook’ları olay tetikleyicileri, API çağrılarını ise durum ve rapor sorguları olarak ayırmak netlik sağlar.
Güvenlik: imza, HTTPS ve erişim kontrolü
Webhook endpoint’iniz internete açık bir kapıdır. Gelen her isteği dost saymak risklidir. En az şu kontrolleri planlayın:
- HTTPS zorunluluğu: Düz HTTP ile giden gövde ve başlıklar okunabilir. Üretimde TLS şarttır.
- İmza doğrulama: Birçok sağlayıcı paylaşılan gizli anahtarla HMAC imzası gönderir. İmza eşleşmezse isteği reddedin.
- Zaman damgası ve yenilik kontrolü: Eski imzalı isteklerin yeniden oynatılmasını (replay) sınırlayın.
- IP allowlist (mümkünse): Sağlayıcı sabit çıkış IP’leri yayınlıyorsa ek katman olarak kullanın; tek başına yeterli saymayın.
- Minimum yetki: Endpoint yalnız ilgili olayları işlesin; geniş admin API’sine köprü kurmasın.
Gizli anahtarları kod deposuna gömmeyin; ortam değişkeni veya gizli yönetim aracı kullanın. Log’larda ham imza ve hassas ödeme alanlarını maskeleyin. Güvenlik adımları ekstra süs değil; yanlış sipariş veya yetkisiz tetiklemeyi önleyen operasyonel zorunluluktur.
Yeniden deneme, idempotency ve hata yönetimi
Webhook’ların zayıf noktası teslimatın her zaman bir kez ve tam sırayla gelmemesidir. Ağ kesintisi, sizin 500 dönmeniz veya sağlayıcı kuyruğu aynı olayı birden fazla kez gönderebilir.
Sağlam bir alıcı tasarımı için:
- Hızlı kabul, sonra işleme: Endpoint mümkünse doğrulayıp 2xx dönsün; ağır işi arka plan kuyruğuna alın. Uzun süren senkron işlemler sağlayıcı timeout’una takılır.
- Idempotency anahtarı: Olay kimliği veya sağlayıcı event id’sini kaydedin. Aynı id ikinci kez gelirse işlemi tekrarlamayın.
- Yeniden deneme politikasını bilin: Sağlayıcının kaç kez, hangi aralıklarla denediğini dokümantasyondan okuyun. 4xx ile 5xx ayrımını bilinçli yapın.
- Dead-letter ve uyarı: Sürekli başarısız olaylar için izleme ve manuel inceleme yolu bırakın.
- Telafi senkronu: Kaçan olaylar için periyodik API mutabakatı planlayın.
Yüksek hacimli olay akışlarında endpoint’in yanıt süresi ve kuyruk derinliği de performans konusu haline gelir. Bu noktada yük ve darboğaz testleri ile gerçekçi senaryoları denemek, canlıda sürprizi azaltır.
Kurulumda izlenecek karar adımları
Teknik detaya girmeden önce iş ve mimari netliği kurun:
- Olay envanteri: Hangi olay gerçekten anlık işlenmeli? Hangisi günlük toplu senkronla yeter?
- Sözleşme ve alanlar: Payload’da hangi alanlar zorunlu? Versiyon değişince ne olacak?
- Güvenlik modeli: İmza algoritması, gizli anahtar rotasyonu, erişim kısıtı.
- Başarı ve hata kodları: Ne zaman 200, ne zaman 4xx, ne zaman 5xx döneceğinizi yazın.
- Gözlemlenebilirlik: Gelen olay sayısı, imza reddi, işleme hatası metrikleri.
- Test planı: Sağlayıcı sandbox’ı, imza testleri, çift gönderim simülasyonu.
Belirsiz bir entegrasyon varsayımını doğrulamak için önce dar kapsamlı bir deneme yapmak da mümkündür. Kritik bir ödeme veya stok senaryosunda proof of concept yaklaşımı, tüm sistemi bağlamadan riski görünür kılar.
KepezWeb olarak özel yazılım ve entegrasyon projelerinde webhook’ları olay kanalı, API’leri sorgu ve telafi kanalı olarak konumlandırmayı tercih ediyoruz. Bu ayrım hem geliştirme kapsamını sadeleştirir hem de operasyon ekibinin hata ayıklamasını kolaylaştırır.
İşletmeler için somut kullanım örnekleri
Webhook’un değerini soyut bırakmamak için sık görülen senaryolar:
- E-ticaret ödemesi: Ödeme tamamlandığında sipariş “ödendi” durumuna geçer; stok ve fatura süreçleri tetiklenir.
- Kargo durumları: Kargo firması “dağıtımda / teslim” olayını gönderir; müşteri bilgilendirme ve destek paneli güncellenir.
- CRM formları: Web sitesi formu CRM’e düşer düşmez satış temsilcisine görev açılır.
- Abonelik yaşam döngüsü: Yenileme, iptal veya ödeme hatası olayları erişim haklarını günceller.
Bu örneklerin ortak noktası, olayın ne zaman olduğu bilgisinin iş kuralını doğrudan etkilemesidir. Sadece rapor için toplanan verilerde webhook şart değildir.
Entegrasyon ihtiyacınız özel yazılım veya mevcut sistemlerin bağlanması şeklindeyse yazılım geliştirme sürecinde olay modeli, güvenlik ve mutabakat adımlarını birlikte tasarlamak ilerideki bakım yükünü azaltır.
Sıkça Sorulan Sorular
Webhook ile API aynı şey midir?
Hayır. API genelde sizin başlattığınız istek-cevap modelidir. Webhook ise kaynak sistemin olay anında sizi bilgilendirdiği itme modelidir. Çoğu entegrasyonda ikisi birlikte kullanılır.
Webhook güvenli midir?
Doğru kurulumla güvenli hale getirilebilir. HTTPS, imza doğrulama, gizli anahtar yönetimi ve gereksiz veriyi loglamama temel önlemlerdir. Endpoint’i korumasız bırakmak risklidir.
Aynı webhook birden fazla kez gelirse ne olur?
Bu beklenen bir durum olabilir. Olay kimliğine göre idempotent işleyin; ikinci kopyayı yok sayın veya yalnızca durum kontrolü yapın. Aksi halde çift sipariş veya çift e-posta gibi hatalar oluşur.
Webhook yoksa entegrasyon yapılamaz mı?
Yapılabilir. Periyodik API polling, dosya aktarımı veya kuyruk tabanlı mimariler alternatif olabilir. Ancak gecikme ve boş sorgu maliyeti artar. Karar, olay sıklığı ve iş toleransına bağlıdır.
Webhook endpoint’i neden hızlı yanıt vermeli?
Çoğu sağlayıcı belirli bir süre içinde HTTP cevabı bekler. Uzun süren işlemler timeout ve gereksiz yeniden denemelere yol açar. Doğrula, kaydet, 2xx dön; ağır işi asenkron kuyruğa bırak.
Webhook tasarımı yalnızca bir URL açmak değil; olay, güvenlik, yeniden deneme ve telafi senkronunu birlikte düşünmektir. KepezWeb ekibiyle entegrasyon mimarinizi sadeleştirmek veya mevcut akışlarınızı gözden geçirmek isterseniz teklif al sayfasından projenizi paylaşabilirsiniz. İhtiyacınıza uygun teknik yaklaşımı birlikte netleştiririz.
