Webhook Nedir?

Sormak yerine haber almak

Başka bir sistemde bir şeyin değişip değişmediğini öğrenmenin iki yolu vardır. Birincisi polling: belirli aralıklarla karşı tarafın API'sine “yeni bir şey var mı?” diye sormak. Sorguların çoğunun cevabı “hayır” olduğu için bu yöntem boşuna trafik üretir; olay ile fark edilmesi arasında da en fazla sorgu aralığı kadar gecikme oluşur. İkincisi push: olay gerçekleştiğinde karşı tarafın sizin belirlediğiniz bir adrese haber vermesi. Webhook, push modelinin web'deki en yaygın uygulamasıdır.

Akış nasıl işler?

1. Webhook'u alacak sistem, HTTPS üzerinden erişilebilen bir uç nokta hazırlar (ör. https://example.com/hooks/payments).
2. Bu adres gönderen servisin paneline veya API'sine kaydedilir ve hangi olayların dinleneceği seçilir.
3. Olay gerçekleştiğinde gönderen servis, olay bilgisini içeren bir HTTP POST isteğini (genellikle JSON) bu adrese yollar.
4. Alıcı isteği doğrular, kaydeder ve hızlıca 2xx bir yanıt döner.

POST /hooks/payments HTTP/1.1
Content-Type: application/json
X-Signature: t=1759400000,v1=5f2b9c0e...

{"id": "evt_8812", "type": "payment.succeeded", "data": {"orderId": 1042, "amount": "1499.90"}}

Başlık adı ve imza formatı servisten servise değişir; örnekteki X-Signature yalnızca temsilîdir.

İmza doğrulama: istek gerçekten kimden geliyor?

Webhook uç noktası internete açık bir adrestir; adresi öğrenen herkes oraya sahte bir “ödeme başarılı” mesajı gönderebilir. Bu yüzden ciddi servislerin çoğu her isteği, yalnızca iki tarafın bildiği bir gizli anahtarla imzalar. Yaygın yöntem, istek gövdesinin HMAC-SHA256 ile imzalanıp sonucun bir başlıkta gönderilmesidir; GitHub bunun için X-Hub-Signature-256, Stripe ise Stripe-Signature başlığını kullanır. GitHub'ın doğrulama rehberi bu sürecin iyi bir örneğidir. Alıcı tarafta dikkat edilmesi gerekenler:

• İmzayı JSON olarak ayrıştırılıp yeniden serileştirilmiş veriyle değil, ham istek gövdesiyle hesaplayın; tek bir boşluk farkı bile imzayı geçersiz kılar.
• İmzaları sabit zamanlı (constant-time) bir karşılaştırma fonksiyonuyla karşılaştırın.
• İmzada zaman damgası varsa, belirli bir süreden eski istekleri reddederek tekrar oynatma (replay) saldırılarını sınırlayın.
• Gizli anahtarı kodun içine değil, ortam değişkenine veya bir gizli anahtar yönetim servisine koyun.

Yeniden denemeler ve tekrar eden olaylar

Gönderen servis başarılı bir yanıt alamazsa (zaman aşımı, 5xx hatası, bağlantı kopması) teslimatı genellikle artan aralıklarla yeniden dener; deneme sayısı ve süresi servise göre değişir. Doğal sonucu şudur: aynı olay size birden fazla kez ulaşabilir. Teslimat çoğu zaman “en az bir kez” garantisiyle yapılır, “tam olarak bir kez” değil. Olayların gönderildikleri sırayla geleceği de garanti edilmez.

Bu yüzden webhook işleyicisi idempotent olmalıdır: her olayın kimliği (örnekteki evt_8812) kaydedilir; daha önce işlenmiş bir kimlik tekrar gelirse hiçbir işlem yapılmadan 200 dönülür. Aksi halde aynı sipariş için iki fatura kesilebilir ya da müşteriye aynı e-posta iki kez gidebilir.

Sağlam bir alıcı için pratikler

• Hızlı yanıt verin: İsteği doğrulayıp bir kuyruğa yazın, fatura oluşturma veya e-posta gönderme gibi uzun işleri arka planda yapın. Uzun süren işlemler gönderen tarafta zaman aşımına ve gereksiz yeniden denemelere yol açar.
• Durum kodunu bilinçli seçin: Gönderen taraf yeniden deneyip denemeyeceğine HTTP durum koduna bakarak karar verir. İmzası geçersiz isteğe 4xx, başarıyla alınmış olaya 2xx dönün.
• Webhook'u tek doğruluk kaynağı saymayın: Kritik durumlarda olay geldikten sonra güncel durumu gönderenin REST API'sinden okuyun.
• Kaçan olayları yakalayın: Webhook'lar çoğu otomasyon senaryosunun tetikleyicisidir ve sessizce kaybolan tek bir olay süreci yarıda bırakabilir. Belirli aralıklarla iki sistemi karşılaştıran bir uzlaştırma (reconciliation) görevi bu açığı kapatır.