Webhook Nedir? Polling ve API Farkı, Güvenlik, Yeniden Deneme ve Uygulama Rehberi

Pazaryerinde sipariş düştü, ama depo ekranında yarım saattir görünmüyor. Ödeme alındı, fakat muhasebe sistemi haberdar değil. Çoğu zaman sorun verinin kendisinde değil, haberin sisteme ulaşma biçimindedir. Webhook nedir sorusunun cevabı tam burada başlar: bir olay olduğunda kaynak sistemin, sizin belirlediğiniz adrese kendiliğinden haber göndermesi.

Bu rehberde webhook'un ne olduğunu, polling (sürekli sorgulama) ve normal API isteğinden farkını, bir webhook'un yapısını, iş sistemlerindeki tipik kullanımını, alıcı tarafın nasıl tasarlanacağını, güvenliği, hata ve yeniden deneme yönetimini, izleme ölçülerini ve altı adımlı uygulama planını anlatıyoruz. Örnek rakamlar temsilîdir; belirli bir sistemin ya da sektörün ölçümü değildir.

Webhook Nedir?

Webhook, bir sistemde olay gerçekleştiğinde (sipariş ödendi, stok değişti, kargo teslim edildi) o sistemin, önceden tanımlanmış bir web adresine olay bilgisini HTTP isteğiyle göndermesidir. Alıcı sistem sormaz; haber gelir. Bu nedenle "ters API" ya da "olay bildirimi" olarak da anılır.

Benzetme basit: polling, posta kutusunu beş dakikada bir kontrol etmektir; çoğu kontrol boş çıkar. Webhook ise telefonla aranmaktır; haber olduğunda çalar. Ama telefon açılmazsa, arayan bir süre sonra yeniden dener; bu ayrıntı yazının büyük kısmını oluşturuyor.

Okumanızı öneririz: API entegrasyonu nedir? Sistemleri birbirine bağlama rehberi

Webhook, Polling ve Normal API İsteği Arasındaki Fark Nedir?

Üçü de sistemler arası veri taşır; fark, girişimi kimin başlattığı ve ne zaman haber verildiğidir. Normal API isteği ihtiyaç duyduğunuz anda veri çekmektir; polling bunu belirli aralıklarla otomatik tekrarlamaktır; webhook ise kaynağın olay anında itmesidir.

Pratikte üçü birlikte kullanılır: olay webhook ile gelir, ayrıntı API isteğiyle çekilir, kaçan olay için de günlük bir uzlaştırma sorgusu çalışır.

Polling Ne Kadar Boşuna Çalışır?

Beş dakikada bir sorgulayan bir sistem günde 288 istek atar (24 saat × 12). Günde gerçekten 10 sipariş geliyorsa, 278 sorgu boş döner: 278 ÷ 288 ≈ %96,5. Üstelik sipariş iki sorgu arasında herhangi bir anda düşebileceğinden ortalama bekleme aralığın yarısıdır: 5 ÷ 2 = 2,5 dakika. Webhook ile aynı haber yaklaşık 1 saniyede gelir.

Aralığı kısaltmak çözüm değildir: dakikada bir sorgulama günde 1.440 istek demektir; gecikme azalır (ortalama 30 saniye), boş istek artar (1.430 ÷ 1.440 ≈ %99,3). Kaynak sistem genellikle istek sınırı da uygular; sınırı aşan sorgulama, gereksiz yere engellenmeye yol açar.

Bir Webhook'un Yapısı Nasıldır?

Bir webhook beş parçadan oluşur. Bunları bilmek, hem kurarken hem hata ararken yol gösterir.

1. Olay (event): Ne olduğunu söyleyen ad; örneğin order.paid (sipariş ödendi).
2. Yük (payload): Olayın verisi; JSON biçiminde olay kimliği, zaman, sipariş numarası, tutar gibi alanlar.
3. Alıcı adresi: Haberin gönderileceği, sizin sisteminizdeki web adresi; kaynak sistemde kaydedilir.
4. İmza başlığı: Mesajın gerçekten kaynaktan geldiğini ve yolda değişmediğini gösteren değer; ortak bir gizli anahtarla üretilir.
5. Yanıt kodu: Alıcının verdiği cevap. 2xx "aldım" demektir; başka bir kod ya da yanıt gelmemesi "ulaşmadı" sayılır ve yeniden denemeyi başlatır.

Örnek olarak şöyle bir mesaj düşünün: olay adı order.paid, olay kimliği evt_8f21, oluşma zamanı, sipariş numarası 1042 ve tutar ₺2.450. Başlıklarda ise gönderim zamanı ve imza yer alır. Alıcı bunu alır, doğrular ve 200 döner.

İş Sistemlerinde Webhook Nerelerde Kullanılır?

Zaman duyarlı ve durum değiştiren her akış adaydır. En yaygın kullanımlar şunlardır.

• Sipariş durumu: Yeni sipariş, iptal ve iade bildirimleri sipariş yönetimine anında düşer.
• Ödeme sonucu: Ödemenin başarılı ya da başarısız olduğu bilgisi, siparişi onaylamak ya da bekletmek için gerekir.
• Stok değişikliği: Bir kanalda satış olunca diğer kanalların stoku güncellenir; gecikme fazla satış riskini artırır.
• Kargo güncellemesi: Yola çıktı, dağıtımda, teslim edildi bilgileri müşteriye ve pazaryerine iletilir.
• Fatura durumu: e-Fatura'nın gönderildi, iletildi ya da hata aldı bilgisi ilgili siparişe yazılır.

Bu akışların nasıl kurulduğunu konu konu şu rehberlerde anlattık:

Okumanızı öneririz: Pazaryeri entegrasyonu nedir? Sipariş, stok ve fiyat akışı

Okumanızı öneririz: Kargo entegrasyonu nedir? Etiket, takip ve mutabakat rehberi

Okumanızı öneririz: e-Fatura entegrasyonu nedir? Fatura durumu ve hata yönetimi

Alıcı Taraf Nasıl Tasarlanmalı?

Alıcının iki kuralı vardır: hızlı yanıt vermek ve aynı olayı iki kez işlememek. İlki çoğu sistemde zaman aşımı yüzünden önemlidir; yanıt birkaç saniyeden uzun sürerse gönderen "ulaşmadı" sayar ve yeniden dener.

Hızlı yanıt ver, işi sonra yap

Alıcı mesajı alır, imzayı doğrular, kuyruğa yazar ve hemen 2xx döner. Asıl iş (stok düşme, fatura kesme) kuyruktan ayrı bir işleyici tarafından yapılır. Böylece ağır bir işlem yanıtı geciktirip gereksiz yeniden denemeye yol açmaz.

Aynı olayı iki kez işleme (idempotency)

Gönderen, yanıtı alamazsa aynı olayı tekrar yollar; ağ sorunlarında alıcı işi yapmış olsa bile yanıt kaybolabilir. Çözüm, her olayın kimliğini saklayıp daha önce işlendiyse atlamaktır.

Örnek: sipariş 1042 için evt_8f21 geldi, stok 50 iken 2 adet düşüldü ve 48 oldu; kimlik "işlendi" tablosuna yazıldı. Gönderen yanıtı alamadığı için aynı olayı yeniden yolladı. Alıcı kimliği tabloda bulur, işlemeden 200 döner; stok 48 kalır. Koruma olmasaydı stok 46'ya inecek, fatura da ikinci kez kesilecekti.

Webhook Güvenliği Nasıl Sağlanır?

Alıcı adresi internete açık olduğundan herkes ona istek atabilir; bu yüzden gelen her mesajın kaynağı doğrulanır. Dört önlem temeldir.

İmza doğrulamada gövdenin işlenmeden, ham haliyle kullanıldığına dikkat edin; JSON'u yeniden biçimlendirirseniz imza tutmaz. Gizli anahtar kod içine değil, güvenli bir ayar alanına konur. Katmanlı koruma ve anahtar saklama konusunun tamamı için aşağıdaki rehbere bakın.

Okumanızı öneririz: API güvenliği nasıl sağlanır? Yetkilendirme, hız sınırı ve webhook imzası

Hata ve Yeniden Deneme Nasıl Yönetilir?

Alıcı kapalıysa ya da hata verirse gönderen, giderek uzayan aralıklarla yeniden dener. Örnekte aralıklar 1, 2, 4 ve 8 dakikadır: denemeler 0., 1., 3., 7. ve 15. dakikada yapılır; toplam beş deneme, 15 dakika. Hepsi başarısızsa olay "ölü mektup" kuyruğuna ya da elle inceleme listesine düşer ve sizi uyarır.

Sıranın korunduğunu varsaymayın. İki olay aynı saniyede farklı yollardan gelebilir; her olayda zaman ya da sürüm alanı bulunmalı, alıcı eski bir mesajın yeni durumu ezmesine izin vermemelidir. Yeniden denemelerin sonunda hâlâ ulaşmayan olaylar için günlük bir uzlaştırma (kaynağa "dünden bu yana ne oldu?" diye sormak) güvenlik ağıdır.

Webhook'un Sağlığı Hangi Ölçülerle İzlenir?

Üç ölçü yeterlidir: teslim başarı oranı, ortalama gecikme ve tekrar oranı. Temsilî bir gün: kaynak 1.000 olay gönderdi; 985'i ilk denemede, 11'i yeniden denemeyle ulaştı, 4'ü ölü mektup kuyruğuna düştü.

• Teslim başarı oranı: ulaşan ÷ gönderilen. Yeniden denemeyle ulaşanlar dahil (985 + 11) ÷ 1.000 = %99,6; ilk denemede 985 ÷ 1.000 = %98,5. Kuyruğa düşen 4 olay %0,4'tür.
• Ortalama gecikme: ilk denemedekiler 1 saniye, yeniden denenen 11 olay ortalama 3 dakika (180 sn) gecikti: (985 × 1 + 11 × 180) ÷ 996 = 2.965 ÷ 996 ≈ 3,0 saniye. Ortalama düşük görünse de uç olaylar için en yüksek değere de bakın.
• Tekrar oranı: alıcı 1.026 istek aldı, 996 farklı olay kimliği vardı; 30 tekrar ÷ 1.026 ≈ %2,9. Oran birden artarsa gönderende ya da alıcının yanıt süresinde sorun vardır.

Bu üç değer için eşik belirleyip aşıldığında uyarı üretin; örneğin başarı oranı %99'un altına inerse haber verin. Eşikler işinize göre belirlenir.

Webhook Kurmanın Maliyeti ve Getirisi Nedir?

Hesabı sahne rakamlarıyla yapalım. Polling aylık 288 × 30 = 8.640 istek, webhook ise 10 × 30 = 300 istek üretir (yeniden deneme payı hariç); istek sayısı yaklaşık %96,5 azalır. Asıl kazanç hızdır: ortalama 2,5 dakikalık gecikme yaklaşık 1 saniyeye iner.

Parasal örnek (temsilî): alıcı uç, imza, kuyruk ve izleme için 6 kişi-gün × ₺9.000 = ₺54.000 yatırım. Aylık getiri: gecikmeli stok yüzünden ayda 2 fazla satış önlenir (2 × ₺600 = ₺1.200) ve elle uzlaştırmadan 3 saat kazanılır (3 × ₺300 = ₺900); toplam ₺2.100. Geri dönüş: 54.000 ÷ 2.100 ≈ 25,7 ay. Tek akış için bu uzun görünür.

Alıcı altyapısı bir kez kurulduğunda ek akışlar ucuzdur. Sipariş, ödeme, stok, kargo ve fatura için beş akış kurarsanız: ilkine ₺54.000, diğer dördüne 2 kişi-gün × ₺9.000 = ₺18.000'den ₺72.000; toplam ₺126.000. Aylık getiri 5 × ₺2.100 = ₺10.500. Geri dönüş: 126.000 ÷ 10.500 = 12 ay. Yani webhook'un değeri tek bir akışta değil, ortak altyapıyı yeniden kullanmada ortaya çıkar. Bu rakamlar örnektir; kendi hacminizle yeniden hesaplayın.

Webhook Entegrasyonu Hangi Adımlarla Kurulur?

Altı adım, düşük riskle ilerlemeyi sağlar.

1. Olayları listeleyin: Hangi olaylar iş için anlamlı? (ödeme, stok, kargo...) Gereksiz olay aboneliği yük getirir.
2. Alıcı ucu yazın: Ham gövdeyi alsın, kuyruğa yazsın, hızlı 2xx dönsün.
3. İmzayı doğrulayın: Gizli anahtar, zaman toleransı ve HTTPS.
4. Tekrar korumasını ekleyin: Olay kimliği tablosu ve sıra bozukluğuna karşı zaman/sürüm kontrolü.
5. Test ve yeniden deneme senaryosu: Alıcıyı bilerek kapatın, aynı olayı iki kez gönderin, geç yanıt verin.
6. İzleyin ve uzlaştırın: Üç ölçü, uyarı eşikleri ve günlük uzlaştırma sorgusu.

Sık Yapılan Webhook Hataları Nelerdir?

• Yanıttan önce işi yapmak: Ağır iş yanıtı geciktirir, gönderen yeniden dener ve tekrar sorunu doğar.
• Tekrar korumasını atlamak: Çift stok düşümü, çift fatura ve çift e-posta en sık sonuçlardır.
• İmzayı doğrulamamak: Adresi bilen herkes sahte sipariş ya da ödeme bildirimi gönderebilir.
• Sıranın korunduğunu varsaymak: Eski mesaj yeni durumu ezer.
• Uzlaştırmayı unutmak: Webhook'a tek başına güvenmek, kaybolan olayları fark edilmez kılar.
• İzlememek: Alıcı sessizce kapandığında günlerce haber fark edilmeyebilir.

Okumanızı öneririz: Sipariş yönetim sistemi nedir? Kanallar arası sipariş akışı

İnovabil ile Entegrasyon ve Olay Tabanlı Akışlar

İnovabil olarak ağırlığımız sıfırdan, firmaya özel yazılım geliştirmektir; entegrasyon bunun önemli bir parçasıdır. Sistemleriniz arasında olay tabanlı akış gerekiyorsa, hangi olayın webhook, hangisinin API sorgusu ya da günlük uzlaştırma ile karşılanacağını gereksinim analizinde yazılı olarak netleştirmenizi öneriyoruz.

Karyak için lojistik ve sevkiyat planlama ile toptan sipariş yönetimi; Sleepy için depo yönetimi ile şikâyet ve destek yönetim sistemi; Kredili Kargo için ön ödemeli kargo sistemi; İZBAN için satın alma sistemi geliştirdik. Sistemlerinizi ve hangi haberlerin gecikmesinin size pahalıya geldiğini kısaca yazın; birlikte bir değerlendirme çıkaralım.

Okumanızı öneririz: Entegrasyon hizmetimiz

Sık Sorulan Sorular