Webhook Nedir? Sistemler Arası Anlık Bildirim Rehberi

Webhook, bir sistemde bir olay gerçekleştiğinde başka bir sisteme otomatik olarak HTTP isteği gönderilmesidir. "Bir şey olduğunda bana haber ver" mantığıyla çalışır. Ödeme tamamlandığında, sipariş oluşturulduğunda veya bir fatura onaylandığında ilgili sistem sizin belirlediğiniz adrese bilgi gönderir.

API sorgulamadan (polling) farkı

Bir ödemenin tamamlanıp tamamlanmadığını öğrenmek için iki yol vardır:

• Polling: Belirli aralıklarla "Ödeme tamamlandı mı?" diye sormak. Gereksiz istekler oluşturur ve gecikmeli bilgi verir.
• Webhook: Ödeme tamamlandığı anda ödeme sağlayıcısı sizin sisteminize bildirim gönderir. Daha verimli ve anlıktır.

Kısacası API'de siz sorarsınız, webhook'ta size söylenir. İkisi birbirini tamamlar; REST temelleri için REST API nedir yazımıza bakabilirsiniz.

Yaygın kullanım senaryoları

• Ödeme sağlayıcısından ödeme başarılı/başarısız bildirimi
• E-ticaret altyapısından yeni sipariş bildirimi
• e-Fatura entegratöründen belge durum değişikliği
• Kod deposundan yeni commit bildirimi ile otomatik yayın
• Form servisinden yeni başvuru bildirimi
• Kargo firmasından teslimat durumu güncellemesi

Nasıl çalışır?

1. Webhook alıcısı olarak sisteminizde bir endpoint oluşturursunuz (örneğin /webhooks/odeme).
2. Bu adresi karşı sistemin paneline kaydedersiniz.
3. Olay gerçekleştiğinde karşı sistem, olay bilgisini genellikle JSON formatında bu adrese POST eder.
4. Sisteminiz isteği doğrular, kaydeder ve hızlıca 2xx yanıtı döner.
5. Asıl iş (stok düşme, e-posta gönderme vb.) arka planda işlenir.

Güvenli bir webhook alıcısının kuralları

1. İmzayı doğrulayın

Webhook adresi herkese açık bir URL'dir. Birisi sahte istek göndererek "ödeme başarılı" bildirimi uydurabilir. Sağlayıcıların çoğu isteği gizli bir anahtarla imzalar (genellikle HMAC). Her istekte imzayı doğrulayın, geçersizse reddedin.

static bool ImzaGecerli(string govde, string gelenImza, string gizliAnahtar)
{
    using var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(gizliAnahtar));
    var hesaplanan = Convert.ToHexString(hmac.ComputeHash(Encoding.UTF8.GetBytes(govde)));
    return CryptographicOperations.FixedTimeEquals(
        Encoding.UTF8.GetBytes(hesaplanan.ToLowerInvariant()),
        Encoding.UTF8.GetBytes(gelenImza.ToLowerInvariant()));
}

İmza formatı sağlayıcıya göre değişir; mutlaka kendi dokümantasyonunu takip edin.

2. Zaman damgasını kontrol edin

Eski bir isteğin tekrar gönderilmesini (replay) önlemek için istekteki zaman damgası makul bir aralıkta değilse reddedin.

3. Idempotent olun

Sağlayıcılar yanıt alamadığında aynı olayı tekrar gönderir. Aynı olay iki kez işlenirse stok iki kez düşebilir veya müşteriye iki e-posta gidebilir. Olay kimliğini kaydedip daha önce işlenmiş olayları atlayın. Bu konu ödeme sistemleri entegrasyonu için hayati önemdedir.

4. Hızlı yanıt verin

Uzun işlemleri webhook isteği içinde yapmayın. Olayı bir kuyruğa veya tabloya kaydedip hemen yanıt verin, işlemeyi arka planda yapın. Aksi halde zaman aşımı nedeniyle tekrar denemeler başlar.

5. Kritik bilgiyi doğrulayın

Özellikle ödeme gibi kritik olaylarda, webhook'taki bilgiye ek olarak sağlayıcının API'sinden işlemin durumunu sorgulayarak teyit etmek iyi bir uygulamadır.

6. Loglayın ve izleyin

Gelen her webhook'u (hassas veriler maskelenerek) kaydedin. Başarısız işlemeler için uyarı kurun.

Test etme

• Sağlayıcıların test ortamlarını ve test olay gönderme özelliklerini kullanın.
• Yerel geliştirmede, yerel sunucunuzu geçici olarak internete açan tünel araçlarından yararlanabilirsiniz.
• Aynı olayı iki kez göndererek idempotency'yi test edin.

Sık sorulan sorular

Webhook ulaşmazsa ne olur?

Çoğu sağlayıcı belirli aralıklarla tekrar dener. Yine de kritik süreçlerde, belirli aralıklarla çalışan bir kontrol görevi ile eksik kalan olayları API üzerinden tamamlamak güvenli bir yedek yöntemdir.

Webhook endpoint'i gizli tutulmalı mı?

URL'nin tahmin edilmesi zor olması faydalıdır ama güvenlik için yeterli değildir. Asıl koruma imza doğrulamasıdır.

Sonuç

Webhook'lar sistemler arasında anlık ve verimli iletişim sağlar. Güvenli bir alıcı; imzayı doğrular, tekrar gönderimlere dayanıklıdır, hızlı yanıt verir ve her şeyi kayıt altına alır. Entegrasyon projeleriniz için teklif isteyebilirsiniz.