Webhook, bir API'nin belirli bir olay gerçekleştiğinde başka bir uygulamaya HTTP isteği göndererek gerçek zamanlı bildirim yapmasıdır. REST API'lerde polling (periyodik sorgulama) yerine webhook kullanmak, kaynak tüketimini azaltır ve veri gecikmesini minimize eder. Doğru tasarlanmış bir webhook sistemi, uygulamalar arasında güvenilir ve hızlı iletişim sağlar.
Webhook Tasarımının Temel Bileşenleri
Bir webhook entegrasyonunda iki taraf vardır: yayıncı (olayı üreten sistem) ve tüketici (webhook'u alan uygulama). Yayıncı, tüketiciden bir webhook URL'si ve genellikle bir gizli anahtar alır. Tasarım sürecinde aşağıdaki kararlar kritik öneme sahiptir:
- Payload yapısı: Olay türü, zaman damgası, benzersiz olay kimliği (event ID) ve ilgili verileri içermelidir.
- Güvenlik: Tüm istekler HTTPS üzerinden yapılmalı ve HMAC imzası ile doğrulanmalıdır.
- İdempotency: Tüketici, aynı event ID'ye sahip birden fazla isteği tekrar işlememelidir.
- Yeniden deneme stratejisi: Başarısız istekler için exponential backoff ve maksimum deneme sayısı belirlenmelidir.
Güvenlik: İmza Doğrulama ve Gizli Anahtar Yönetimi
Webhook güvenliğinin temel taşı, imza doğrulamadır. Yayıncı, payload'u gizli bir anahtar ile HMAC-SHA256 kullanarak imzalar ve bu imzayı bir HTTP header'ında (örneğin X-Signature) gönderir. Tüketici, aynı anahtarla imzayı yeniden hesaplar ve eşleşmezse isteği reddeder. Anahtarın güvenli değişimi için ilk bağlantıda bir handshake mekanizması kullanılabilir. Backend API'lerde JWT Token Yönetimi rehberimizdeki gibi, webhook anahtarlarını da çevresel değişkenlerde veya bir gizli yönetici (secret manager) hizmetinde saklayın.
Webhook tüketicisi, her webhook çağrısını idempotent hale getirmelidir; aksi halde aynı olay birden fazla kez işlenebilir. Bu, veri tutarlılığını bozar ve yan etkilere yol açar.
İdempotency ve Yinelenen İstekleri Yönetme
İdempotency, webhook tasarımının en kritik ama sıklıkla göz ardı edilen yönüdür. Her webhook payload'ı, benzersiz bir event_id içermelidir. Tüketici, bu ID'yi veritabanında veya bir önbellekte saklayarak daha önce işlenmiş olayları tespit eder. Örneğin, bir ödeme webhook'unda aynı ödeme onayı iki kez alınırsa, idempotency sayesinde mükerrer işlem yapılmaz. API Caching Stratejileri makalemizde olduğu gibi, işlenmiş event ID'lerini kısa süreli önbelleğe almak da etkili bir yöntemdir.
Yeniden Deneme (Retry) Stratejileri
Webhook istekleri her zaman başarılı olmayabilir. Ağ sorunları, tüketici sunucusunun geçici olarak erişilemez olması veya zaman aşımı gibi durumlarda yeniden deneme mekanizması devreye girer. İyi bir strateji şunları içerir:
- Exponential backoff: Her başarısız denemeden sonra bekleme süresini katlayarak artırın (ör. 1 dakika, 2 dakika, 4 dakika...).
- Maksimum deneme sayısı: Genellikle 3-5 deneme yeterlidir. Aşırı deneme kaynak israfına yol açar.
- Dead letter queue (DLQ): Tüm denemeler başarısız olursa, webhook'u bir DLQ'ya taşıyarak manuel müdahale veya log analizi için saklayın.
Bu yaklaşımlar, iOS'da URLSession ile Zaman Aşımı ve Retry Stratejileri yazımızda anlattığımız prensiplerle benzerlik gösterir. Retry sırasında aynı event ID'yi kullanmaya devam edin.
Webhook ve Polling Karşılaştırması
| Özellik | Webhook | Polling |
|---|---|---|
| Gecikme | Gerçek zamanlı (olay anında bildirim) | Polling aralığına bağlı (ortalama yarı aralık kadar gecikme) |
| Kaynak Kullanımı | Düşük (sadece olay olduğunda istek) | Yüksek (sürekli istek) |
| Karmaşıklık | Yayıncı ve tüketici taraflarında ek mimari gerektirir | Basit, sadece tüketici tarafında periyodik sorgulama |
| Güvenilirlik | İstekler kaybolabilir; retry ve idempotency şart | Her polling isteği bağımsızdır; kayıp riski düşük |
| Kullanım Senaryosu | Anlık bildirim gerektiren durumlar (ödeme, mesajlaşma) | Veri değişim sıklığı düşük veya toleranslı uygulamalar |
Sık Yapılan Hatalar ve Çözümleri
Webhook entegrasyonunda en yaygın hatalardan biri, tüketici tarafında payload doğrulamasının ihmal edilmesidir. İmza doğrulaması yapılmazsa, kötü niyetli aktörler sahte webhook'lar gönderebilir. Diğer bir hata, webhook URL'sinin değişebileceğini hesaba katmamaktır. URL değişikliği durumunda yayıncının güncellenmesi için bir API veya panel sağlayın. Ayrıca, tüm webhook'ların aynı anda aynı sunucuya gönderilmesi, tüketici sunucusunu aşırı yükleyebilir; bu nedenle kuyruk yapısı (queue) kullanmak faydalıdır.
İzleme ve Hata Ayıklama
Webhook sisteminizin sağlığını izlemek için her isteğin başarı/başarısızlık durumunu loglayın. Başarısız isteklerin nedenlerini (zaman aşımı, 4xx/5xx hataları) analiz edin. Yayıncı tarafında webhook teslimat raporları sunuyorsa, bunları düzenli olarak kontrol edin. Açık kaynak araçlar (örneğin, n8n'de Hata Yönetimi makalemizdeki teknikleri benzer şekilde uygulayabilirsiniz.
Sonuç
Webhook'lar, REST API ekosisteminde olay odaklı iletişimin anahtarıdır. Güçlü bir güvenlik, idempotency, akıllı retry stratejisi ve sürekli izleme ile webhook entegrasyonunuzu sağlam temellere oturtabilirsiniz. Unutmayın: doğru tasarlanmış bir webhook, sistemler arası veri akışını pürüzsüz ve güvenilir hale getirir.
Sık Sorulan Sorular
Webhook nedir ve REST API'de nasıl çalışır?
Webhook, bir API'nin belirli bir olay gerçekleştiğinde önceden tanımlanmış bir URL'ye HTTP isteği göndermesidir. REST API'de polling yerine kullanılarak gerçek zamanlı bildirim sağlar.
Webhook güvenliği için hangi yöntemler kullanılmalıdır?
HTTPS zorunludur. HMAC imzası ile payload doğrulaması yapılmalı, gizli anahtar güvenli saklanmalı ve tüketici tarafında imza her istekte kontrol edilmelidir.
Webhook retry stratejisi nasıl olmalıdır?
Exponential backoff kullanarak bekleme sürelerini artırın, maksimum deneme sayısını 3-5 ile sınırlayın ve tüm denemeler başarısız olursa dead letter queue'ya taşıyın.
Webhook ve polling arasındaki temel fark nedir?
Webhook olay anında bildirim gönderirken, polling tüketicinin periyodik olarak sorgulama yapmasını gerektirir. Webhook daha düşük gecikme ve kaynak kullanımı sunar, ancak daha karmaşık bir mimari gerektirir.
Webhook entegrasyonunda en sık yapılan hata nedir?
En sık yapılan hata, tüketici tarafında idempotency sağlanmamasıdır. Aynı olay birden fazla kez işlenirse veri tutarlılığı bozulur. Ayrıca imza doğrulamasının atlanması da güvenlik açığı oluşturur.
