Webhook Çalışmıyor: Olaylar Neden Ulaşmıyor ve Nasıl Test Edilir?

[Kadir]

Webhook entegrasyonunda sağlayıcı tarafında olay oluşmasına rağmen kendi sisteminize bildirim gelmiyorsa sorun yalnızca webhook URL'sinde olmayabilir. Yanlış event seçimi, HTTPS problemi, firewall, imza doğrulama hatası, timeout veya uygulamanın 2xx dışı cevap vermesi webhook teslimatını engelleyebilir.

Bu rehberde webhook çalışmadığında olayın sağlayıcıdan çıkışından uygulamanızda işlenmesine kadar bütün zinciri adım adım kontrol edeceğiz.


Webhook nedir?

Basitleştirilmiş olarak webhook:

Kod:

Bir olay oluşur ↓ SaaS sağlayıcısı sizin URL'nize HTTP isteği gönderir ↓ Uygulamanız olayı işler

mantığıyla çalışır.

Örneğin:

Kod:

Ödeme başarılı ↓ payment.completed webhook ↓ Sipariş sistemi güncellenir

Webhook çoğu zaman API entegrasyonunun tamamlayıcısıdır. Uygulamanız sağlayıcıya yaptığı doğrudan API çağrılarında 401, 403, 429 veya 500 hataları alıyorsa API Bağlantısı Çalışmıyor rehberindeki kontrolleri ayrıca uygulayın.

1. Webhook URL'si doğru mu?

Sağlayıcı panelindeki URL'yi kontrol edin.

Örneğin:

Kod:

https://site.com/webhook

yerine eski:

Kod:

https://test.site.com/webhook

kalabilir.

Test ve canlı ortam URL'lerini karıştırmayın.


2. Endpoint internetten erişilebilir mi?

Webhook sağlayıcısı local bilgisayarınızdaki:

Kod:

http://localhost/webhook

adresine doğrudan ulaşamaz.

Endpoint internetten erişilebilir olmalıdır.

Geliştirme sırasında güvenilir tunnel araçları kullanılabilir.


3. HTTPS düzgün çalışıyor mu?

Birçok servis webhook için HTTPS bekler.

Kontrol edin:

• Sertifika geçerli mi?
  
• Domain doğru mu?
  
• Sertifika süresi dolmuş mu?
  
• TLS bağlantısı kuruluyor mu?
  

4. Doğru event'lere abone oldunuz mu?

Webhook URL'sini eklemek tek başına yeterli olmayabilir.

Örneğin yalnız:

Kod:

customer.created

event'ine aboneyseniz:

Kod:

payment.completed

olayını alamazsınız.

Sağlayıcı panelindeki event listesini kontrol edin.


5. Test ve production event'lerini karıştırmayın

Bazı SaaS servislerinde test ortamı ile canlı ortam webhook yapılandırmaları ayrıdır.

Örneğin:

Kod:

Test ödeme → Test webhook Canlı ödeme → Production webhook

şeklinde olabilir.

Test panelinde event görüp canlı endpoint'te beklemek hatalı teşhise yol açabilir.


6. Sağlayıcının webhook teslimat loglarını kontrol edin

Mümkünse şu bilgileri inceleyin:

• Event ID
  
• Gönderim zamanı
  
• Hedef URL
  
• HTTP response kodu
  
• Retry sayısı
  
• Response body
  

Örneğin:

Kod:

HTTP 404

ile:

Kod:

HTTP 500

farklı problemlerdir.


7. Endpoint hangi HTTP kodunu döndürüyor?

Webhook endpoint'i başarılı işleme sonrasında genellikle 2xx sınıfında cevap vermelidir.

Örneğin:

Kod:

200 OK

veya sağlayıcının kabul ettiği başka bir 2xx kodu.

Webhook işlenmesine rağmen yanlışlıkla:

Kod:

500

döndürüyorsanız sağlayıcı olayı başarısız kabul edip tekrar gönderebilir.


8. Webhook endpoint'i çok yavaş mı?

Webhook isteği geldiğinde aynı request içerisinde:

Kod:

PDF oluştur E-posta gönder Büyük API senkronizasyonu yap Rapor üret

gibi uzun işlemler yapıyorsanız sağlayıcının timeout süresi aşılabilir.

Daha sağlıklı yapı bazı sistemlerde:

Kod:

Webhook al ↓ Doğrula ↓ Queue'ya yaz ↓ 2xx cevap ver ↓ Arka planda işle

şeklinde olabilir.


9. Redirect kullanılıyor mu?

Webhook URL'si:

Kod:

http://site.com/webhook

adresinden:

Kod:

https://site.com/webhook

adresine yönleniyor olabilir.

Bazı webhook servisleri redirect davranışını farklı ele alabilir.

Mümkün olduğunda panelde doğrudan final HTTPS URL'sini kullanın.


10. Firewall veya WAF isteği engelliyor olabilir

Cloudflare, ModSecurity veya başka bir güvenlik sistemi webhook POST isteğini şüpheli görebilir.

Kontrol edin:

• Security log
  
• WAF event
  
• 403 kayıtları
  
• IP engellemeleri
  

Webhook güvenliği için bütün firewall'u kapatmak yerine ilgili kuralı teşhis edin.


11. Request body gerçekten geliyor mu?

Endpoint'in geçici güvenli logunda:

• HTTP method
  
• Content-Type
  
• Body uzunluğu
  
• Event ID
  

gibi bilgileri kaydedin.

Ancak ödeme veya kullanıcı verisi içeriyorsa bütün body'yi kontrolsüz loglamayın.


12. JSON parse ediliyor mu?

Webhook şu formatta JSON gönderiyor olabilir:

Kod:

{   "event": "order.created",   "id": "evt_123" }

Uygulamanız form-data bekliyorsa veri boş görünebilir.

Content-Type ile body parse yönteminin uyumlu olduğundan emin olun.


13. İmza doğrulama başarısız olabilir

Güvenli webhook sistemleri request'in gerçekten sağlayıcıdan geldiğini doğrulamak için signature kullanabilir.

Örneğin header:

Kod:

Webhook-Signature

içerebilir.

Sağlayıcı dokümantasyonundaki algoritmayı birebir uygulayın.


14. Raw body ile signature doğrulamaya dikkat edin

Bazı servislerde imza:

ham request body

üzerinden hesaplanır.

JSON'u parse edip yeniden serialize ettikten sonra signature kontrolü yaparsanız byte dizisi değişebilir ve doğrulama başarısız olabilir.

Bu nedenle sağlayıcının önerdiği doğrulama yöntemini kullanın.


15. Webhook secret doğru mu?

Test ve canlı ortamın webhook secret değerleri farklı olabilir.

Şu kombinasyon çalışmayabilir:

Kod:

Production event + Test webhook secret

Secret değerlerini loglarda veya forumda paylaşmayın.


16. Aynı event birden fazla kez gelebilir

Webhook sistemleri teslimat garantisi sağlamak için başarısız görünen event'i tekrar gönderebilir.

Bu nedenle:

Kod:

evt_123

event'i iki kez gelirse iki sipariş oluşturmamalısınız.

Event ID veya işlem ID üzerinden idempotent işleme tasarlayın.


17. Event'lerin sıralı geleceğini varsaymayın

Dağıtık sistemlerde iki event her zaman oluşturuldukları sırada ulaşmayabilir.

Örneğin:

Kod:

customer.updated

bazı durumlarda başka event'ten önce işlenebilir.

İş mantığınızı yalnız network sırasına bağlamayın.


18. Retry mekanizmasını öğrenin

Sağlayıcının webhook dokümantasyonundan:

• Kaç kez retry yaptığı
  
• Ne kadar beklediği
  
• Hangi HTTP kodlarında retry yaptığı
  
• Event'in manuel yeniden gönderilip gönderilemediği
  

bilgilerini kontrol edin.


19. 200 dönmesine rağmen işlenmiyorsa uygulama loguna bakın

Webhook sağlayıcısı:

Kod:

200 OK

görüyor olabilir.

Ancak uygulamanız event'i kaydetmeden 200 dönüyor olabilir.

Şu zinciri ayrı izleyin:

Kod:

HTTP request geldi ↓ Signature doğrulandı ↓ Event parse edildi ↓ DB kaydı oluştu ↓ İşlem tamamlandı

20. Test event gönderin

Sağlayıcı panelinde test webhook özelliği varsa kullanın.

Gerçek müşteriyi veya siparişi beklemeden endpoint'in:

• İsteği aldığını
  
• Doğruladığını
  
• 2xx döndürdüğünü
  
• Event'i işlediğini
  

kontrol edebilirsiniz.


Webhook hızlı teşhis sırası

1. Webhook URL doğru mu?
   
2. HTTPS çalışıyor mu?
   
3. Doğru event seçildi mi?
   
4. Test/canlı ortam doğru mu?
   
5. Sağlayıcı gönderim logunda ne yazıyor?
   
6. HTTP kodu nedir?
   
7. Endpoint timeout oluyor mu?
   
8. WAF engelliyor mu?
   
9. Body doğru parse ediliyor mu?
   
10. Signature doğru mu?
    
11. Secret doğru ortamdan mı?
    
12. Mükerrer event kontrolü var mı?
    

Güvenlik notu

Webhook endpoint'inizi yalnız URL gizli olduğu için güvenli kabul etmeyin.

Mümkün olduğunda:

• Signature doğrulaması
  
• TLS
  
• Secret yönetimi
  
• Idempotency
  
• Güvenli loglama
  

kullanın.

Webhook secret, API anahtarları ve kullanıcı yetkileri de genel SaaS erişim denetiminin parçasıdır. Bu alanları topluca kontrol etmek için SaaS Güvenliği: 2FA, Kullanıcı Yetkileri ve Eski Hesaplar Nasıl Denetlenir? rehberini kullanabilirsiniz.

Sonuç

Webhook çalışmadığında doğru teşhis zinciri:

Event oluştu → sağlayıcı gönderdi → ağ ulaştırdı → endpoint kabul etti → imza doğrulandı → uygulama işledi

şeklindedir.

Bu zincirin hangi aşamada koptuğunu bulmadan webhook URL'sini tekrar tekrar değiştirmek problemi çözmeyebilir.

Önce sağlayıcının teslimat logu ile kendi uygulama logunuzu aynı event ID üzerinden karşılaştırın.