Webhook Nedir? İki Sistemin Birbirini Anında Nasıl Tetiklediğini Gerçek Bir Örnekle Anlatıyorum

Bir e-ticaret sitesi işlettiğini düşün. Müşteri kart bilgilerini giriyor, Stripe ödemeyi onaylıyor — ama bu senin sunucunun hiç haberi olmadan, Stripe'ın kendi altyapısında oluyor. Sistemin bunu nasıl 'öğrenecek'? İki yol var: ya sistemin Stripe'a her birkaç saniyede bir 'ödeme geldi mi, geldi mi, geldi mi?' diye soruyor (buna polling denir) ya da Stripe, ödeme anında sana kendisi haber veriyor. İkinci yöntemin adı webhook — ve bugün internetteki neredeyse her 'anında' entegrasyonun altında bu var: bir WhatsApp mesajının saniyeler içinde CRM'ine düşmesi, GitHub'a kod push'ladığında CI/CD'nin otomatik tetiklenmesi, bir form doldurulduğunda Slack kanalına bildirim gitmesi. Hepsi aynı fikrin farklı kılıklardaki uygulamaları.

##Webhook Nedir, Basitçe?

Webhook, bir sistemde bir şey olduğunda — bir ödeme, bir form gönderimi, bir kod push'u — o sistemin, önceden verdiğin bir adrese (URL) otomatik olarak bir HTTP isteği (genellikle POST) atmasıdır. Yani 'bu olay gerçekleştiğinde beni ara, adresim bu' demenin teknik karşılığı. Apartmanda kapıcı örneğine benzetebilirsin: kapıcıya kargon geldi mi diye her saat inip sormak yerine, ona telefon numaranı bırakıyorsun; kargo geldiğinde o seni arıyor. Sen sürekli soru sormak zorunda kalmıyorsun, o olay olduğunda haber veriyor. Bu basit fikir, modern yazılımın büyük kısmının birbirine gerçek zamanlı bağlanmasını sağlıyor — Stripe, GitHub, Shopify, Twilio, WhatsApp Business API, Typeform gibi hemen hemen her ciddi SaaS ürünü webhook destekliyor ve webhook nedir sorusunun cevabı aslında bu kadar basit: olay tabanlı, karşı tarafın başlattığı bir bildirim mekanizması.

##Webhook ile Sürekli API Sorgusu (Polling) Arasındaki Fark

Webhook'u anlamanın en kolay yolu alternatifiyle karşılaştırmak. Polling'de senin sistemin belirli aralıklarla karşı tarafa 'yeni bir şey var mı?' diye soruyor; çoğu zaman cevap 'hayır' oluyor ve bu binlerce boşuna istek anlamına geliyor. Webhook'ta ise karşı taraf gerçekten bir şey olduğunda seni arıyor, boşuna soru yok. Fark küçük bir detay gibi görünse de, ölçek büyüdükçe hem sunucu maliyetini hem de olayın fark edilme hızını doğrudan etkiliyor.

• ▸Gecikme: Polling'de olay ile fark edilmesi arasında saniyeler-dakikalar geçebilir; webhook'ta genelde saniyenin altında haber alırsın.
• ▸Sunucu yükü: Polling binlerce gereksiz istek üretir, çoğu 'değişiklik yok' cevabıyla sonuçlanır; webhook sadece gerçek olaylarda çalışır.
• ▸Kurulum karmaşıklığı: Polling'i kurmak kolaydır (zamanlanmış bir görev yeter); webhook bir endpoint yazmanı ve güvenliğini düşünmeni ister.
• ▸Ne zaman polling daha mantıklı: karşı sistem webhook desteklemiyorsa, ya da olay sıklığı zaten çok düşükse (günde bir senkronizasyon gibi).

##Yaygın Webhook Kullanım Alanları

Webhook'u soyut bir kavram olarak değil, günlük kullandığın araçların arkasında sessizce çalışan bir mekanizma olarak görmek daha kolay anlaşılıyor. Bugün kullandığın birçok entegrasyon aslında bir webhook'un üstüne kurulu:

• ▸Stripe/iyzico: ödeme başarılı veya başarısız olduğunda siparişi güncellemek
• ▸GitHub/GitLab: koda push yapıldığında CI/CD pipeline'ını otomatik tetiklemek
• ▸Shopify/WooCommerce: yeni bir sipariş geldiğinde depo veya muhasebe sistemine haber vermek
• ▸Twilio/WhatsApp Business API: gelen bir mesajı anında CRM'e veya destek ekranına düşürmek
• ▸Typeform/Google Forms: bir form dolduğunda otomatik olarak bir lead kaydı oluşturmak
• ▸Slack/Discord: bir sistemde hata veya önemli bir olay olduğunda kanala bildirim atmak
• ▸Calendly: bir randevu alındığında takvime ve hatırlatma sistemine otomatik eklemek

##Bir Webhook Aslında Nasıl Çalışır? (Teknik Perde Arkası)

Perde arkasında üç parça var: bir olay kaynağı (Stripe gibi), senin yazdığın bir 'endpoint' (genelde /webhooks/stripe gibi bir URL) ve aradaki HTTP isteği. Olay gerçekleştiğinde kaynak sistem o URL'ye bir POST isteği atar; gövdesinde (body) genelde JSON formatında olayın detayları vardır — hangi ödeme, ne kadar tutar, hangi müşteri, hangi zaman damgası. Senin endpoint'in bu isteği alır, doğrular ve kendi iş mantığını çalıştırır: veritabanına yazar, bir kuyruğa görev ekler, başka bir servise haber verir. Teknik olarak webhook, normal bir API çağrısından farklı bir protokol değildir — aynı HTTP, aynı JSON. Fark, isteği kimin başlattığıdır: normal API çağrısında sen istersin, webhook'ta karşı taraf sana gönderir.

>İmza doğrulama neden şart?

Endpoint URL'in herkese açık olduğu için, teorik olarak biri sana sahte bir 'ödeme başarılı' isteği gönderip bedava ürün alabilir. Bunu engellemek için ciddi servisler her isteğe bir imza (signature) ekler — sen bu imzayı kendi gizli anahtarınla doğrulayıp isteğin gerçekten o servisten geldiğini teyit edersin. Stripe'ın stripe-signature header'ı, GitHub'ın X-Hub-Signature'ı bunun somut örnekleri. İmza doğrulamadan gelen her isteği işleyen bir webhook endpoint'i, ciddi bir güvenlik açığıdır — bu, bir API anahtarını herkese açık bırakmakla aynı kategoride bir hata.

##Webhook mu, WebSocket mü? Karıştırılan İki Kavram

İkisi de 'gerçek zamanlı' kelimesiyle anılınca kolayca karışıyor ama çok farklı işler görüyorlar. Webhook, tek seferlik bir olay bildirimidir — bir şey olur, bir istek gönderilir, bağlantı kapanır. WebSocket ise sürekli açık kalan iki yönlü bir bağlantıdır; bir sohbet uygulamasında mesajların anlık akması, bir borsa ekranında fiyatların sürekli güncellenmesi WebSocket'in işi. Basit bir kural: olay seyrek ve tek yönlüyse (ödeme onayı, form gönderimi) webhook yeterli ve daha basit; sürekli, yoğun, iki yönlü bir veri akışı gerekiyorsa (canlı sohbet, canlı fiyat, ortak düzenleme ekranı) WebSocket'e ihtiyacın var. Çoğu SaaS entegrasyonu aslında webhook'un yettiği türden — bu yüzden WebSocket'e göre çok daha yaygın karşına çıkıyor.

##Gerçek Bir Senaryo: Ödeme Webhook'tan Siparişe Nasıl Dönüşüyor

Küçük bir e-ticaret sitesi işlettiğini düşün. Müşteri kart bilgilerini giriyor, Stripe ödemeyi işliyor — bu senin sunucunun hiç haberi olmadan, Stripe'ın kendi altyapısında gerçekleşiyor. Ödeme onaylandığı an Stripe, senin önceden tanımladığın https://siten.com/webhooks/stripe adresine bir POST isteği atıyor; içinde payment_intent.succeeded olayı ve ödemenin detayları var. Senin endpoint'in şunları yapıyor: önce imzayı doğruluyor; sonra veritabanında ilgili siparişi 'ödendi' olarak işaretliyor; kargo sistemine 'bu siparişi hazırla' diye bir görev düşürüyor; müşteriye otomatik bir teşekkür e-postası tetikliyor. Bütün bunlar, müşteri ekranda 'ödeme başarılı' yazısını görmeden önce, bir-iki saniye içinde oluyor. Peki ağ arızası yüzünden aynı webhook isteği iki kez gelirse ne olur? İyi kurulmuş bir sistem bunu öngörür — her istekle gelen benzersiz olay kimliğini (event id) kontrol eder, aynı kimliği daha önce işlediyse ikinci isteği sessizce yok sayar. Buna idempotency denir ve gerçek dünyada webhook'ların neredeyse hiçbiri bu kontrol olmadan güvenle çalışmaz. Sen hiçbir zaman Stripe'a 'ödeme geldi mi?' diye sormadın — Stripe sana geldi, sen de yalnızca doğru şekilde dinlemeyi kurdun.

##Webhook Kurarken Nelere Dikkat Etmeli

Webhook kurmak beş dakikalık bir iş gibi görünür ama sağlam bir kurulumun gözden kaçırılan birkaç önemli detayı var:

• ▸İmza doğrulama: her gelen isteğin gerçekten beklediğin kaynaktan geldiğini teyit et, imzasız isteği reddet.
• ▸İdempotency: aynı olay ağ hatası yüzünden iki kez gelebilir — sistemin aynı ödemeyi iki kez işlememesi lazım.
• ▸Hızlı yanıt ver: endpoint'in isteği alır almaz 200 OK dönmeli, asıl işi arka planda bir kuyrukla yap; yoksa kaynak sistem 'başarısız' sanıp gereksiz yere tekrar dener.
• ▸Retry ve loglama: çoğu servis başarısız webhook'u birkaç kez tekrar dener ama sonsuza kadar değil — başarısız istekleri loglayıp manuel kontrol edebilmelisin.
• ▸Yerel test: Stripe CLI, ngrok gibi araçlarla webhook'u canlıya çıkmadan önce kendi bilgisayarında test edebilirsin.

##Sık Sorulan Sorular

>Webhook ile normal bir API çağrısı arasındaki fark tam olarak ne?

Normal bir API çağrısında sen karşı tarafa 'bana şu veriyi ver' diye istekte bulunursun — inisiyatif sende. Webhook'ta inisiyatif karşı taraftadır: bir şey olduğunda o sana bir istek gönderir. Teknik olarak ikisi de aynı protokolü (HTTP) ve genelde aynı formatı (JSON) kullanır; fark isteği kimin, ne zaman başlattığıdır.

>Webhook'lar güvenli mi, biri sahte istek gönderebilir mi?

Doğru kurulmazsa hayır, güvenli değildir — endpoint URL'in herkese açık olduğu için teorik olarak herkes istek atabilir. Bu yüzden imza doğrulama (signature verification) zorunlu kabul edilmeli; imzasız veya yanlış imzalı isteği reddetmeyen bir webhook endpoint'i ciddi bir güvenlik açığıdır. Ayrıca endpoint'ini yalnızca beklenen kaynağın IP aralıklarından gelen isteklere açmak (varsa) ek bir güvenlik katmanı sağlar.

>Webhook endpoint'im geçici olarak çökerse veri kaybolur mu?

Genelde hayır. Stripe, GitHub gibi ciddi servisler başarısız (200 dönmeyen) webhook isteklerini artan aralıklarla saatler, hatta günler boyunca tekrar dener. Ama bu bir garanti değil — bazı servisler belirli bir süre sonra denemeyi bırakır. Kritik iş akışları için endpoint'inin loglarını izlemen ve gerekirse kaynak sistemin kendi panelinden (Stripe Dashboard'daki 'Events' sekmesi gibi) manuel senkronizasyon yapabilmen gerekir.

>Küçük bir işletme veya tek kişilik bir proje webhook'a ne zaman ihtiyaç duyar?

Bir üçüncü parti servisin (ödeme, mesajlaşma, form, CRM) bir olayına anında tepki vermen gerektiği her an. Ödeme onayında sipariş oluşturmak, bir form doldurulduğunda CRM'e lead düşürmek, bir mesaj geldiğinde otomatik yanıt tetiklemek — bunların hepsi webhook'la çözülür. Sadece günde bir kez bir raporu senkronize ediyorsan, zamanlanmış bir görev (cron) muhtemelen webhook'tan daha basit ve yeterlidir.

>Webhook için ayrı bir sunucuya mı ihtiyacım var?

Hayır, çoğu zaman gerekmez. Webhook, mevcut backend'ine eklediğin bir route/endpoint'ten ibarettir — ayrı bir servis kurmana gerek yok. Trafiğin çok büyüdüğü veya birden fazla kaynaktan yüzlerce webhook aynı anda geldiği noktada, bu isteği anında bir kuyruğa (queue) atıp ana uygulamadan ayrı, ölçeklenebilir bir işçi (worker) ile işlemek mantıklı hale gelir; ama küçük-orta ölçekli bir proje için mevcut backend'ine bir endpoint eklemek fazlasıyla yeterlidir.

Webhook, iki sistemi birbirine bağlamanın küçük ama kritik bir parçası — API entegrasyonlarının nasıl çalıştığını merak ediyorsan ilgili yazılarıma göz atabilir ya da kendi projendeki bir entegrasyon için /contact üzerinden yazabilirsin.