Webhook Nedir? API ile Farkı, Nasıl Çalışır ve Güvenliği

Webhook nedir ve tek cümlede ne işe yarar?

Webhook, bir sistemde belirli bir olay gerçekleştiğinde o sistemin sizin belirlediğiniz bir adrese otomatik HTTP isteği göndermesidir. Yani bilgiyi siz sormazsınız, olay olunca karşı taraf size haber verir. Ödeme onayı, yeni form kaydı veya kod deposuna gelen bir değişiklik bu yolla anında ulaşır.

Basit bir benzetme yapalım: kargonuzu her saat arayıp "geldi mi?" diye sormak polling yöntemidir. Kargo firmasının paket kapıya ulaştığında size SMS atması ise webhook mantığıdır. İkinci yöntemde hem siz yorulmazsınız hem de firma gereksiz telefonlarla uğraşmaz. Bu yazıda Talha Aslan ve ekibi olarak webhook nedir sorusunu kavramsal düzeyde, ama sahada işinize yarayacak derinlikte cevaplıyoruz.

Önce olay tabanlı itme modelini anlatacağız. Ardından API polling ve WebSocket ile farkını bir tabloyla göstereceğiz. Son olarak imza doğrulama, yeniden deneme, idempotency ve güvenlik konularını adım adım ele alacağız. Kod bloğu vermeyeceğiz; amacımız mantığı oturtmak.

Webhook nedir sorusunda "olay tabanlı itme" ne anlama gelir?

Olay tabanlı itme (event-driven push), verinin talep üzerine değil olay anında gönderilmesi demektir. Klasik bir API çağrısında istemci sunucuya gider ve "bana son siparişleri ver" der. Webhook modelinde ise yön tersine döner: sunucu, olay gerçekleşince istemcinin adresine gider.

Bu modelde üç parça vardır. İlki olayı üreten sistemdir; örneğin bir ödeme sağlayıcısı. İkincisi olayın tanımıdır; "ödeme başarılı" ya da "abonelik iptal edildi" gibi. Üçüncüsü de sizin sunucunuzdaki dinleyici adrestir, yani endpoint. Olay oluştuğunda sağlayıcı bu adrese genellikle JSON gövdeli bir POST isteği yollar.

Dolayısıyla webhook aslında yeni bir protokol değildir. Düz HTTP üzerinde çalışan bir anlaşmadır: "Şu olay olursa şu adrese şu biçimde haber ver." Bu sadelik onu çok yaygın hale getirir. Ödeme altyapıları, kod depoları, form araçları, e-posta servisleri ve CRM sistemleri bu anlaşmayı neredeyse standart olarak sunar.

Webhook adım adım nasıl çalışır?

Akışı somutlaştırmak için tipik bir webhook yaşam döngüsünü sıralayalım. Sağlayıcıdan sağlayıcıya ayrıntı değişse de iskelet hemen hemen aynıdır.

1. Sunucunuzda herkese açık, HTTPS ile çalışan bir dinleyici adres hazırlarsınız.
2. Sağlayıcının panelinde ya da API'sinde bu adresi kaydeder, hangi olayları dinlemek istediğinizi seçersiniz.
3. Sağlayıcı size paylaşılan bir gizli anahtar (secret) verir veya siz belirlersiniz.
4. Olay gerçekleşince sağlayıcı olayı JSON olarak paketler, gizli anahtarla imzalar ve adresinize POST eder.
5. Siz imzayı doğrular, isteği kuyruğa alır ve hızlıca 2xx durum koduyla yanıt verirsiniz.
6. Asıl iş (sipariş güncelleme, e-posta gönderme) arka planda ayrı bir işlemde yürür.
7. Yanıt gelmezse veya hata dönerse sağlayıcı, politikasına göre isteği daha sonra yeniden dener.

Bu akışta en çok atlanan adım beşincisidir. Birçok ekip işi istek içinde bitirmeye çalışır, yanıt gecikir ve sağlayıcı isteği başarısız sayar. Stripe'ın resmi webhook belgesi de karmaşık mantığı çalıştırmadan önce hızlıca başarılı yanıt dönmenizi önerir.

Webhook ile API arasındaki fark nedir?

Kısacası API bir kapıdır, webhook ise o kapıdan size gelen bir zildir. API, bir yazılımın başka bir yazılımla konuşmak için sunduğu kurallar bütünüdür; siz istediğinizde çağırırsınız. Webhook ise genellikle bir API'nin parçası olarak gelir ve iletişimi sağlayıcı başlatır.

Bu nedenle "webhook mu API mi?" sorusu biraz yanıltıcıdır. Çoğu entegrasyonda ikisini birlikte kullanırsınız. Örneğin ödeme sağlayıcısı webhook ile "şu ödeme tamamlandı" der. Siz de ayrıntıları güvenle almak için aynı sağlayıcının API'sine ödeme kimliğiyle sorgu atarsınız.

API kavramını sıfırdan merak ediyorsanız API nedir yazımızda uç noktaları, istek ve yanıt yapısını ayrıntılı anlattık. Sorgu dilini esnek kullanan modeli ise GraphQL ve REST farkı yazısında bulabilirsiniz. Burada yalnızca webhook tarafına odaklanıyoruz.

Pratik bir kural verelim: "Bir şey değiştiğinde haberim olsun" ihtiyacında webhook düşünün. "İstediğim an veri çekeyim" ihtiyacında doğrudan API çağrısı yeterlidir.

Polling ile webhook arasında nasıl seçim yaparsınız?

Polling, istemcinin belirli aralıklarla sunucuya "yeni bir şey var mı?" diye sormasıdır. Kurulumu kolaydır, çünkü dışarıya açık bir adrese ihtiyacınız yoktur. Ancak çoğu istek boş döner ve hem sizin hem sağlayıcının kaynağını harcar.

Ayrıca polling'de gecikme, sorgu aralığınıza bağlıdır. Beş dakikada bir sorarsanız bir ödeme bildirimi en kötü durumda beş dakika sonra fark edilir. Aralığı kısaltırsanız bu kez istek sayısı artar ve sağlayıcının hız sınırına (rate limit) takılabilirsiniz.

Webhook ise olay anında gelir ve boş istek üretmez. Öte yandan bir dinleyici adres yayınlamanız, güvenliğini sağlamanız ve kaçan olaylara karşı plan yapmanız gerekir. Bu yüzden sahada en sağlam yaklaşım genellikle karma modeldir: anlık bildirim için webhook, ara sıra çalışan bir mutabakat (reconciliation) işi için polling.

Örnek senaryo: bir e-ticaret sitesi ödeme onaylarını webhook ile alıyor. Ek olarak gece bir kez sağlayıcının API'sinden günün ödemelerini çekip kendi kayıtlarıyla karşılaştırıyor. Böylece sunucu bakımı sırasında kaçan bir bildirim bile ertesi sabah tespit edilebiliyor.

Webhook, API polling ve WebSocket karşılaştırma tablosu

Üç yaklaşım sık sık karıştırılır. Aşağıdaki tablo, hangisinin hangi soruya cevap verdiğini özetliyor. Değerler kavramsaldır; gerçek performans altyapınıza göre değişir.

WebSocket'i ayrıntılı merak ediyorsanız WebSocket nedir yazımıza göz atın. Kısaca söylersek WebSocket kullanıcı arayüzüne canlı veri akıtmak için, webhook ise iki sunucu arasında olay haberi taşımak için idealdir.

Webhook isteğinin içinde neler bulunur?

Bir webhook isteği sıradan bir HTTP POST isteğidir. Yine de içeriği belli bir düzen izler. Gövde genellikle JSON biçimindedir ve olayın türünü, benzersiz kimliğini, oluşturulma zamanını ve ilgili nesneyi taşır.

• Olay türü: "payment succeeded" ya da "push" gibi, ne olduğunu söyleyen alan.
• Olay kimliği: Her olaya özgü benzersiz değer; tekrar gelen istekleri ayıklamak için kritik.
• Zaman damgası: Olayın ne zaman oluştuğu; eski isteklerin tekrar oynatılmasını engellemeye yarar.
• Veri nesnesi: Ödeme, form kaydı ya da depo değişikliği gibi asıl içerik.
• İmza başlığı: Gövdenin gizli anahtarla üretilmiş imzası; isteğin gerçekten sağlayıcıdan geldiğini kanıtlar.

Başlık adları sağlayıcıya göre değişir. Örneğin GitHub imzayı ayrı bir başlıkta SHA-256 tabanlı HMAC olarak gönderir. Stripe ise imzayı ve zaman damgasını kendi başlığında birlikte iletir. Bu nedenle her zaman kullandığınız servisin güncel belgesini esas alın.

Gövde biçimleri konusunda kafanız karışıyorsa YAML ve JSON farkını anlattığımız yazı iyi bir başlangıç olur.

Webhook imza doğrulama neden şarttır?

Dinleyici adresiniz internete açıktır. Dolayısıyla adresi bilen herkes oraya sahte bir "ödeme başarılı" isteği gönderebilir. İmza doğrulama yapmazsanız sisteminiz parası ödenmemiş bir siparişi onaylayabilir. Bu, webhook güvenliğinin en temel kuralıdır.

Çözüm HMAC adlı yöntemdir. HMAC (Hash-based Message Authentication Code), mesaj ile gizli anahtarı birleştirip bir özet fonksiyonundan geçirerek doğrulama kodu üretir. Yöntemin tanımı RFC 2104 belgesinde yer alır. Gizli anahtarı yalnızca siz ve sağlayıcı bildiği için doğru imzayı başka kimse üretemez.

Doğrulama mantığı şöyle işler: sağlayıcı gövdeyi anahtarla imzalar ve imzayı başlığa koyar. Siz de gelen ham gövdeyi aynı anahtarla imzalarsınız. İki değer eşleşirse istek gerçektir; eşleşmezse isteği reddedersiniz.

Burada iki ince nokta var. Birincisi, imzayı ham gövde üzerinden hesaplamalısınız; JSON'u ayrıştırıp yeniden yazarsanız boşluklar değişir ve imza tutmaz. İkincisi, karşılaştırmayı sabit süreli (constant-time) bir fonksiyonla yapmalısınız. GitHub'ın teslimat doğrulama belgesi de düz eşitlik karşılaştırması yerine bu yöntemi önerir.

HMAC imzasını doğrularken en sık hangi hatalar yapılır?

Sahada gördüğümüz hatalar genellikle birkaç kalıba toplanır. Aşağıdaki liste, kendi kodunuzu gözden geçirirken kontrol listesi olarak işe yarar.

• Çatının (framework) gövdeyi otomatik ayrıştırması yüzünden ham gövdeye erişememek.
• Test ortamının anahtarını canlı ortamda kullanmak ya da tersini yapmak.
• Gizli anahtarı kodun içine gömüp depoya yüklemek.
• İmza başlığındaki ön eki (ör. algoritma adı) temizlemeden karşılaştırmak.
• Zaman damgasını hiç kontrol etmemek; böylece eski bir isteğin tekrar oynatılmasına kapı açmak.
• İmza tutmadığında yine de 200 dönmek ve hatayı sessizce yutmak.

Gizli anahtar için uzun ve rastgele bir değer seçin. Hızlıca güçlü bir değer üretmek isterseniz şifre oluşturucu aracımızı kullanabilirsiniz. Anahtarı ortam değişkeninde ya da bir gizli bilgi yöneticisinde saklayın. Ayrıca belirli aralıklarla anahtarı yenileyin; çoğu sağlayıcı geçiş sırasında iki anahtarı aynı anda destekler.

Token tabanlı kimlik doğrulamayla imza doğrulamayı karıştırmamak gerekir. Kullanıcı oturumları için JWT yazımızda anlattığımız yapı kullanılır. Webhook'ta ise amaç kullanıcıyı değil, mesajın kaynağını ve bütünlüğünü doğrulamaktır.

Yeniden deneme (retry) mekanizması nasıl işler?

İnternet kusursuz değildir. Sunucunuz o an bakımda olabilir, ağ kopabilir veya kodunuz hata verebilir. Bu yüzden ciddi sağlayıcılar başarısız teslimatları belirli bir politikayla yeniden dener.

Genel kural şudur: sağlayıcı 2xx dışında bir yanıt alırsa ya da belirli sürede yanıt alamazsa isteği başarısız sayar. Ardından artan aralıklarla (exponential backoff) tekrar gönderir. Stripe belgesi canlı modda başarısız olayların birkaç gün boyunca tekrar denendiğini belirtir. GitHub ise başarısız teslimatları otomatik olarak yeniden göndermez; panelden ya da API'den elle tekrar teslim etmenizi bekler.

Görüldüğü gibi politika servisten servise ciddi biçimde farklıdır. Deneme sayısı, aralıklar ve zaman aşımı gibi değerleri rakam olarak ezberlemeyin; güncel değeri sağlayıcının resmi belgesinden kontrol edin.

Sizin tarafınızda yapmanız gereken ise net: isteği hızlıca kabul edin, işi kuyruğa atın ve 2xx dönün. Böylece yavaş bir veritabanı sorgusu yüzünden gereksiz tekrarlar oluşmaz. Ayrıca hata dönmeniz gereken durumları bilinçli seçin; imza hatasında 4xx, geçici altyapı sorununda 5xx dönmek sağlayıcıya doğru sinyali verir.

Idempotency webhook'ta neden hayati önem taşır?

Yeniden deneme mekanizmasının doğal sonucu şudur: aynı olay size birden fazla kez gelebilir. Stripe da belgesinde endpoint'inizin zaman zaman aynı olayı birden çok kez alabileceğini açıkça söyler. Eğer kodunuz her istekte sipariş açıyorsa müşteriniz iki kez ürün alır ya da iki fatura görür.

Idempotency, aynı işlemi bir kez de yapsanız on kez de yapsanız sonucun değişmemesi demektir. Webhook bağlamında en pratik yöntem olay kimliğini kaydetmektir. Yeni bir istek geldiğinde önce kimliğe bakarsınız; daha önce işlediyseniz hiçbir şey yapmadan 2xx dönersiniz.

Bunu sağlamlaştırmak için veritabanında olay kimliği sütununa benzersiz kısıt (unique constraint) koyun. Böylece iki istek aynı anda gelse bile yalnızca biri yazılabilir. Kavramın tüm ayrıntılarını idempotency nedir yazımızda anlattık; burada tekrar etmiyoruz.

Bir başka ince nokta da sıralamadır. Olaylar her zaman oluştukları sırayla gelmeyebilir. Örneğin "abonelik güncellendi" olayı "abonelik oluşturuldu" olayından önce ulaşabilir. Bu yüzden durum değiştirirken olayın zaman damgasına veya nesnenin güncel halini API'den çekmeye yaslanın.

Webhook güvenliği için hangi önlemleri almalısınız?

İmza doğrulama tek başına iyi bir başlangıçtır ama yeterli değildir. Katmanlı düşünmek gerekir. Aşağıdaki kontrol listesini kurulumdan önce ekibinizle birlikte gözden geçirin.

1. Dinleyici adresi yalnızca HTTPS üzerinden yayınlayın; düz HTTP ile gizli veri taşımayın.
2. Her isteğin imzasını ham gövde üzerinden ve sabit süreli karşılaştırmayla doğrulayın.
3. Zaman damgasını kontrol edin; makul pencerenin dışındaki istekleri reddedin.
4. Olay kimliğini kaydedip tekrar eden istekleri ayıklayın.
5. Gövdeye körü körüne güvenmeyin; kritik işlemlerde nesnenin son halini sağlayıcının API'sinden çekin.
6. Gelen veriyi doğrulayın ve beklenmeyen alanları yok sayın.
7. Adres için tahmin edilmesi zor bir yol kullanın; ancak bunu tek güvenlik katmanı saymayın.
8. Sağlayıcı IP aralıklarını yayınlıyorsa ek katman olarak izin listesi düşünebilirsiniz.
9. Kayıt (log) tutun ama kart verisi ya da kişisel veri gibi hassas alanları maskeleyin.

Kişisel veri taşıyan webhook'larda KVKK ve GDPR yükümlülüklerini de unutmayın. Bu yazı hukuki danışmanlık değildir; veri işleme konusunda hukuk danışmanınızın görüşünü alın.

Ödeme bildiriminde webhook nasıl kullanılır?

Webhook'un en kritik kullanım alanı ödemelerdir. Örnek senaryo: müşteri ödeme sayfasında kartını girer, 3D Secure adımını tamamlar ve tarayıcıyı kapatır. Siz yalnızca tarayıcının geri dönüşüne güvenirseniz bu siparişi asla onaylayamazsınız.

Oysa ödeme sağlayıcısı, işlem tamamlanınca sunucunuza webhook gönderir. Siz imzayı doğrularsınız, olay kimliğini kontrol edersiniz ve siparişi "ödendi" durumuna çekersiniz. Ardından onay e-postası ve stok düşümü gibi işler kuyruktan yürür.

Bu yüzden sahada ödeme entegrasyonlarında altın kural şudur: siparişin kesin durumunu tarayıcı yönlendirmesine değil, sunucudan sunucuya gelen bildirime bağlayın. Ödeme altyapısı seçerken webhook desteğini de kriter yapın; ayrıntılar için sanal POS seçimi yazımıza bakabilirsiniz.

Ayrıca iade, itiraz (chargeback) ve abonelik yenileme gibi olaylar da genellikle webhook ile gelir. Bunları dinlemezseniz muhasebe kayıtlarınız gerçek durumdan sessizce kopar.

Form ve CRM entegrasyonunda webhook ne sağlar?

İkinci yaygın senaryo form ve müşteri ilişkileri yönetimidir. Örneğin web sitenizdeki teklif formu doldurulduğunda form aracı bir webhook gönderir. Bu istek, kaydı anında CRM'e işler ve satış ekibine bildirim düşer.

Polling ile aynı işi yapsaydınız formlar dakikalar sonra görünürdü. Hızlı dönüş yapılan potansiyel müşteri ile saatler sonra aranan potansiyel müşteri arasındaki fark ise çoğu sektörde belirgindir. Üstelik webhook sayesinde reklam kaynağı, UTM etiketleri ve sayfa bilgisi de kayıtla birlikte taşınabilir.

Bu kurguyu uçtan uca nasıl tasarladığımızı CRM entegrasyonlu web sitesi yazımızda anlattık. Tersi yönde de webhook kullanabilirsiniz: CRM'de bir fırsat "kazanıldı" durumuna geçince muhasebe ya da proje aracınıza otomatik kayıt açılabilir.

Kod deposu tarafında da benzer bir akış vardır. GitHub, depoya yeni bir değişiklik gönderildiğinde webhook ile derleme sunucusunu tetikler. Böylece sürekli entegrasyon hattı kimse düğmeye basmadan çalışmaya başlar.

Webhook endpoint'inizi nasıl test edersiniz?

Webhook'u test etmenin zorluğu, isteği sizin değil karşı tarafın göndermesidir. Ancak çoğu sağlayıcı bu iş için kolaylık sunar. Panelde "test olayı gönder" benzeri bir seçenek, geçmiş teslimatların listesi ve her teslimatın yanıt kodu genellikle yer alır.

• Önce test ortamında (sandbox) ayrı bir endpoint ve ayrı gizli anahtar kullanın.
• Yerel geliştirmede sağlayıcının resmi komut satırı aracı varsa olayları bilgisayarınıza yönlendirmek için onu tercih edin.
• Geçerli imza, geçersiz imza, eski zaman damgası ve aynı olayın iki kez gelmesi senaryolarını ayrı ayrı deneyin.
• Sağlayıcının teslimat geçmişinde yanıt sürelerini izleyin.
• Canlıya geçince ilk günlerde hata oranını yakından takip edin.

Python ile yerel ortam kuruyorsanız sanal ortam hatalarıyla karşılaşabilirsiniz. Bu konuyu pip externally managed environment hatası yazımızda çözdük; böylece test aracını sistem Python'unu bozmadan kurabilirsiniz.

Webhook işlerken performans ve ölçek nasıl korunur?

Trafik arttığında en büyük risk, dinleyicinin her isteği senkron işlemesidir. Kampanya gününde dakikada yüzlerce ödeme olayı geldiğini düşünün. Her biri veritabanına yazıyor, e-posta gönderiyor ve stok düşüyorsa yanıtlar gecikir, sağlayıcı tekrar dener ve yük katlanır.

Bu nedenle sağlam mimaride dinleyici yalnızca üç iş yapar: imzayı doğrular, olayı kuyruğa yazar ve 2xx döner. Kuyruktaki olayları ayrı işçi süreçler (worker) kendi hızında tüketir. Böylece bir yavaşlık dinleyiciyi kilitlemez.

Ayrıca başarısız işlenen olaylar için ayrı bir "ölü mektup" (dead letter) kuyruğu tutmak iyi bir alışkanlıktır. Hata çözülünce bu olayları tekrar işlersiniz. Sık okunan referans verileri için önbellek kullanmak da yükü azaltır; konuya önbellekleme yazımızda değindik.

Son olarak izleme kurun. Gelen olay sayısı, imza hatası oranı, kuyruk uzunluğu ve işleme süresi gibi metrikleri bir panelde görün. Böylece sorun müşteriye yansımadan fark edilir.

Webhook kullanmamanız gereken durumlar var mı?

Evet, var. Webhook her ihtiyaca uygun değildir. Örneğin sağlayıcı webhook sunmuyorsa elinizde polling dışında seçenek kalmaz. Benzer biçimde sunucunuzu dış dünyaya açamıyorsanız, yani kapalı bir kurum ağındaysanız gelen istekleri alamazsınız.

Tarayıcıdaki kullanıcıya anlık veri göstermek istiyorsanız da webhook doğrudan çözüm değildir. Çünkü tarayıcı bir HTTP sunucusu değildir ve dışarıdan istek kabul etmez. Bu durumda webhook sunucunuza gelir, siz de veriyi WebSocket ya da benzeri bir kanalla arayüze iletirsiniz.

Çok yüksek hacimli veri akışlarında da olay başına bir HTTP isteği verimsiz kalabilir. Bu senaryolarda mesaj kuyruğu ya da olay akışı platformları daha uygun olabilir. Kısacası webhook, düşük ve orta hacimli, sunucudan sunucuya olay bildirimleri için en sade ve en yaygın yoldur.

Webhook nedir sorusunda sık karıştırılan terimler hangileri?

Webhook nedir diye araştıran okurların önemli bir kısmı birkaç komşu terimi aynı şey sanıyor. Bu karışıklık, yanlış mimari kararlarına yol açabiliyor. Bu yüzden en sık gördüğümüz eşleşmeleri kısa notlarla ayıralım.

• Callback (geri çağırma): Genel programlama kavramıdır; bir iş bitince çağrılan fonksiyon demektir. Webhook, bu fikrin HTTP üzerinden sistemler arası uygulanmış halidir.
• Push bildirimi: Telefonda gördüğünüz bildirimdir ve son kullanıcıya gider. Webhook ise bir sunucuya gider, kullanıcı onu görmez.
• Reverse API: Bazı kaynaklar webhook için bu ifadeyi kullanır. Kastedilen, iletişim yönünün tersine dönmesidir.
• Olay akışı (event stream): Sürekli akan, sıralı olay kayıtlarıdır. Webhook ise tek tek, bağımsız teslimatlardır.

Öte yandan Zapier benzeri otomasyon araçlarında "webhook tetikleyicisi" diye bir adım görürsünüz. Bu adım, aracın size özel bir dinleyici adres üretmesi demektir. Yani mantık tamamen aynıdır; yalnızca endpoint'i siz değil araç barındırır.

Webhook olay aboneliğini nasıl sade tutarsınız?

Birçok sağlayıcı size "tüm olaylar" seçeneği sunar. İlk bakışta pratik görünür, ama sahada sorun üretir. Çünkü dinleyiciniz hiç kullanmadığı yüzlerce olayı almaya, doğrulamaya ve kaydetmeye başlar.

Bu yüzden yalnızca iş akışınızın gerçekten ihtiyaç duyduğu olaylara abone olun. Örneğin bir abonelik sitesi için ödeme başarılı, ödeme başarısız, abonelik iptal ve iade olayları çoğu zaman yeterlidir. Yeni bir özellik ekledikçe listeyi bilinçli olarak genişletirsiniz.

Ayrıca farklı amaçlar için ayrı endpoint'ler kullanmak bakımı kolaylaştırır. Ödeme olayları bir adrese, CRM olayları başka bir adrese gidebilir. Böylece bir taraftaki hata diğerini etkilemez ve log incelemesi çok daha hızlı yapılır. Sade bir abonelik listesi hem güvenlik yüzeyini küçültür hem de sunucu maliyetinizi düşürür.

Webhook kurulumunda maliyet ve bakım nasıl planlanır?

Webhook kurmak ilk bakışta tek bir adres yazmak gibi görünür. Ancak canlıda uzun süre sorunsuz çalışması için bakım planı gerekir. Sahada en çok gözden kaçan kalem, sağlayıcının olay şemasını zamanla değiştirmesidir.

Örneğin sağlayıcı yeni bir alan ekleyebilir ya da API sürümünü yükseltebilir. Kodunuz beklenmeyen alanları yok sayacak biçimde yazılmadıysa bir gün aniden hata almaya başlarsınız. Bu nedenle olay sürümünü kaydedin ve sağlayıcının sürüm notlarını takip edin.

Ayrıca alan adı, SSL sertifikası ve sunucu taşıma işlemleri de webhook'ları etkiler. Endpoint adresi değişirse sağlayıcı panelindeki kaydı da güncellemeniz gerekir. Aksi halde olaylar boşluğa gider ve kimse fark etmez. Kısacası her webhook için bir sahip, bir izleme paneli ve bir güncelleme takvimi belirleyin; böylece entegrasyon sahipsiz kalmaz.

Webhook nedir öğrendikten sonra işletmeniz için pratik kontrol listesi

Webhook nedir, nasıl çalışır ve nerede risk taşır sorularını ele aldık. Şimdi bir entegrasyonu canlıya almadan önce sormanız gereken soruları tek listede toplayalım.

• Hangi olayları gerçekten dinlememiz gerekiyor; gereksiz olay aboneliği var mı?
• Endpoint HTTPS ile mi çalışıyor ve imza doğrulaması ham gövde üzerinden mi?
• Gizli anahtar kodda değil, güvenli bir yerde mi saklanıyor?
• Olay kimliğiyle tekrar eden istekleri ayıklıyor muyuz?
• İşi kuyruğa alıp hızlıca 2xx dönüyor muyuz?
• Sağlayıcının yeniden deneme politikasını belgeden okuduk mu?
• Kaçan olaylar için periyodik mutabakat işimiz var mı?
• Loglarda hassas veriler maskeleniyor mu?

Bu listedeki her madde kâğıt üzerinde basit görünür. Ancak ödeme, stok ve CRM gibi birbirine bağlı sistemlerde tek bir eksik madde günler süren veri tutarsızlığına yol açabilir. Entegrasyonunuzu uçtan uca tasarlamak isterseniz özel yazılım geliştirme hizmetimiz kapsamında ekibimizle birlikte planlayabiliriz.

Webhook konusunda kısaca neyi aklınızda tutmalısınız?

Özetle webhook, "olay olunca haber ver" anlaşmasıdır. API'nin yerine geçmez; onu tamamlar. Polling'e göre daha hızlı ve verimlidir, WebSocket'e göre ise sunucular arası bildirimde daha sadedir.

Ancak bu sadelik bir sorumluluk getirir. İmzayı doğrulamak, tekrarları ayıklamak, hızlı yanıt vermek ve kaçan olayları yakalamak sizin işinizdir. Bu dört alışkanlığı oturtursanız webhook altyapınız yıllarca sorunsuz çalışır.

Son tavsiyemiz şu: her sağlayıcının belgesini ayrı ayrı okuyun. Başlık adları, yeniden deneme süreleri ve imza biçimleri farklıdır. Webhook nedir sorusunun genel cevabı aynı kalsa da ayrıntılar servisten servise değişir.