- Katılım
- 21 May 2023
- Mesajlar
- 712
- Tepki
- 17
- Puan
- 18
Bir ödeme aldığınızda siteniz bunu nereden öğreniyor? İki yol var: her birkaç dakikada bir "yeni bir şey var mı" diye sormak ya da olay gerçekleştiğinde haberin size gelmesini beklemek. İkincisinin adı webhook.
Bu yazı webhook'un ne olduğunu, sürekli sormaktan farkını, kaydın nasıl yapıldığını ve gelen verinin hangi biçimde ulaştığını GitHub ile Stripe'ın kendi geliştirici belgelerinden okuyarak toparlıyor.
Tanım: haber size geliyor
GitHub'ın webhook belgesi, webhook'ları bir yazılım sisteminde olan olaylara abone olmak ve o olaylar gerçekleştiğinde sunucunuza otomatik veri teslimi almak olarak tanımlıyor.
Belge farkı da açıkça koyuyor: webhook'lar veriyi olay olduğu anda almak için kullanılıyor; alternatifi ise API'yi aralıklarla çağırıp veri var mı diye bakmak. Aradaki ayrım, sorunun kimin sorduğu.
Bir kez ilgilenmek yeter
Aynı belgedeki cümle mekanizmanın özünü veriyor: bir olayla ilgilendiğinizi yalnız bir kez, webhook'u oluştururken bildiriyorsunuz. Sonrasında akış kendiliğinden işliyor.
Kaydı oluştururken bir adres belirtiyor ve hangi olaylara abone olacağınızı seçiyorsunuz. Bu yüzden webhook'un çalışması için sizin tarafınızda dinleyen bir uç noktanın bulunması gerekiyor.
- Sorgulama: Siz düzenli aralıklarla soruyorsunuz, çoğu yanıt boş dönüyor.
- Webhook: Olay olduğunda karşı taraf sizin adresinize veri gönderiyor.
- Ortak nokta: İki yolda da kimlik doğrulama ve hata yönetimi sizin sorumluluğunuzda.
Nerelerde kullanılıyor?
GitHub'ın belgesi somut senaryolar sayıyor: dış bir sunucuda sürekli tümleştirme akışını tetiklemek, bir gözden geçirme yapıldığında işbirliği platformuna bildirim göndermek, dış bir konu takip aracını güncellemek, üretim sunucusuna dağıtım yapmak ve denetim amacıyla olayları kaydetmek.
Bu listeye bakınca ortak desen görünüyor: bir sistemde olan biteni başka bir sistemin öğrenmesi gereken her yerde webhook devreye giriyor.
Veri hangi biçimde geliyor?
Stripe'ın webhook belgesi, uç noktayı kaydettikten sonra hesapta olaylar gerçekleştiğinde gerçek zamanlı verinin gönderildiğini söylüyor. Belgeye göre olaylar HTTPS üzerinden, olay bilgisini içeren bir JSON gövdesi olarak uygulamanıza ulaşıyor.
Belge bunun neden değerli olduğunu da örnekliyor: müşterinin bankası bir ödemeyi onayladığında, müşteri bir ödemeye itiraz ettiğinde ya da yinelenen bir ödeme başarılı olduğunda haberdar oluyorsunuz. Bunlar sizin tetiklemediğiniz, sonradan gelen olaylar.
Püf nokta' Alıntı:
Uç noktanın karşılaması gereken şartlar
Stripe'ın belgesi iki koşulu net yazıyor: kayıtlı uç noktalar herkese açık HTTPS adresleri olmalı ve bir hesapta en fazla on altı webhook uç noktası kaydedilebiliyor.
Belge yerel geliştirme için de yol gösteriyor: herkese açık bir HTTPS adresiniz yoksa geçici bir adres üreten bir tünel aracı kullanabilir ya da kaydı yapmadan önce sağlayıcının komut satırı aracıyla yerelde deneyebilirsiniz.
Tek bir uç noktayı birden çok olay türünü karşılayacak biçimde kaydetmek de mümkün; belge ayrı olaylar için ayrı uç noktalar kurulabileceğini de söylüyor.
Güvenlik tarafı
Adresiniz herkese açık olduğu için gelen isteğin gerçekten beklediğiniz taraftan geldiğini doğrulamak gerekiyor. Anahtarların istemci tarafında saklanmasının neden riskli olduğunu API anahtarı yazımızda anlatmıştık; aynı dikkat webhook uç noktası için de geçerli.
Karşı taraftan gelen verinin eksik ya da tekrarlı olabileceğini hesaba katmak da gerekiyor. Benzer bir tuzağı API sayfalaması yazımızda ele almıştık. Otomatik akışların önbellek yüzünden eski veriyle çalışması ise ayrı bir konu; onu da GitHub Actions önbellek yazımızda görebilirsiniz.
Teslimat başarısız olursa ne oluyor?
Webhook'un zayıf noktası burada. Sizin uç noktanız o an kapalıysa, olay gerçekleşmiş ama haber ulaşmamış oluyor. Bu yüzden sağlayıcılar teslim edilemeyen olaylar için ayrı akışlar tanımlıyor; Stripe'ın belgesinde bu başlıklar teslim edilememiş olayların işlenmesi ve kurtarılamayan olayların ele alınması olarak ayrı ayrı geçiyor.
Pratik sonuç şu: webhook'u tek gerçek kaynağı saymak yerine, kritik durumlarda karşı tarafın API'sinden doğrulama yapmak gerekiyor.
Aynı olay iki kez gelirse
Ağ üzerinden yapılan her teslimatta olduğu gibi, bir bildirim tekrar edebilir. Uygulamanızın aynı olayı iki kez işlediğinde ikinci kez yan etki üretmemesi gerekiyor.
Bunun en yalın yolu, gelen olayın kimliğini kaydedip daha önce işlenmiş olanları atlamak. Aksi hâlde tek bir ödeme iki sipariş, tek bir yorum iki bildirim üretebiliyor.
Sık Sorulan Sorular
Webhook nedir?
GitHub'ın tanımıyla, bir sistemdeki olaylara abone olup o olaylar gerçekleştiğinde sunucunuza otomatik veri teslimi almak.
API çağrısından farkı ne?
Belgeye göre webhook veriyi olay anında alıyor; alternatifi API'yi aralıklarla çağırıp veri olup olmadığına bakmak.
Veri hangi biçimde geliyor?
Stripe'ın belgesi olayların HTTPS üzerinden, olay bilgisini içeren JSON gövdesiyle gönderildiğini yazıyor.
Uç noktam ne olmalı?
Kayıtlı uç noktaların herkese açık HTTPS adresleri olması gerekiyor.
Kaç tane webhook kaydedebilirim?
Stripe'ın belgesi bir hesapta en fazla on altı uç nokta kaydedilebildiğini belirtiyor.
Özetle
Webhook, ilgilendiğiniz olayı bir kez bildirip sonrasında verinin size gelmesini sağlayan yapı. Sorgulamanın tersine akış karşı taraftan başlıyor, veri genellikle HTTPS üzerinden JSON olarak ulaşıyor ve uç noktanın herkese açık olması gerekiyor. Açık bir adres tuttuğunuz için doğrulama ve tekrar eden teslimatlar sizin tarafınızda çözülmesi gereken konular.
Sisteminizde hangi olayları hâlâ aralıklarla sorarak öğreniyorsunuz?
Güncelleme: 1 Eylül 2026. GitHub'ın webhook tanıtım belgesi ile Stripe'ın webhook uç noktası belgesi kontrol edildi.
Dijital Dünyanıza Yön Veren Pusula
