Webhook güvenliği ve idempotency: tekrar, sıra ve kuyruk

Kimler için?

Ödeme, mağaza, e-posta veya dış servis olaylarını alan backend geliştiricileri.

Başlamadan önce

Sağlayıcının imza sözleşmesi, kalıcı olay tablosu ve iş kuyruğu.

1. Kimlik doğrulamayı ham gövdeyle yapın

Sağlayıcının tanımladığı imza yöntemini aynen uygulayın. İmza ham body üzerinden hesaplanıyorsa JSON parse edip yeniden serialize edilen metin aynı olmayabilir. İmza anahtarı ve tam payload loglanmamalıdır. Sağlayıcı timestamp kontrolü sunuyorsa uygun tolerans ve saat senkronunu tasarlayın; kendi rastgele HMAC formatınızı sağlayıcı formatı yerine koymayın.

2. Kalıcı kayıt ve hızlı kabul sınırı oluşturun

Önce doğrulanmış olay kimliğini, kaynağını ve durumunu saklayın. Kalıcı kayda alınmadan başarı cevabı vermek, sunucu düşerse olayı kaybettirebilir. Uzun dış servis çağrılarını HTTP handler içinde bitirmeye çalışmayın. Başarı kodunun sağlayıcı için ne anlama geldiğini okuyun; queue’ya alınmış olay ile tamamlanmış iş aynı durum değildir.

3. Tekrarı veritabanı kuralıyla engelleyin

Sadece bellekte “daha önce gördüm” seti tutmak süreç yeniden başlayınca kaybolur. Kaynak ve olay kimliği için benzersizlik kuralı kullanın. İş etkisiyle processed durumunun tutarlılığını transaction veya outbox yaklaşımıyla kurun. Harici bir servis etkisinde aynı transaction’a güvenemezsiniz; o servisin idempotency mekanizmasını da kullanmanız gerekebilir.

Webhook → İmza doğrulama → UNIQUE(provider, event_id) kayıt
        → Kalıcı outbox → Worker → İş etkisi → processed
Tekrar olay → önceki durum / güvenli yeniden işleme

4. Sırasız olayları durum doğrulamasıyla ele alın

Bir abonelik güncellemesi önce, önceki durum olayı sonra gelebilir. Eski olay yeni entitlement’ı geri çevirmemelidir. Sıra numarası veya kaynak sürümü varsa kullanın; kritik durumlarda yetkili sağlayıcıdan güncel kaydı tekrar alın. Olayın gönderilme zamanı ile sisteminizin alma zamanını ayrı saklayın. Her sağlayıcının sıralama garantisi aynı değildir.

5. Retry ve başarısız işler görünür olsun

Geçici bağlantı hatası ile geçersiz iş verisini ayırın. Sınırlı retry ve jitter kullanın; belli bir sınırdan sonra inceleme kuyruğuna taşıyın. Yeniden çalıştırma operatör işlemi denetlenebilir olmalıdır. İmza doğrulamayı bypass ederek eski olayı “düzeltmek” yerine saklanmış güvenilir kayıttan kontrollü replay yapın.

6. Hata enjeksiyonuyla doğrulayın

Aynı olayı iki kez gönderin; iş etkisi tamamlandıktan sonra worker’ı durdurup durum kaydının toparlanmasını deneyin. İmzayı bozun, eski timestamp kullanın ve olayları ters sırayla iletin. Kritik metrikler en eski iş yaşı, tekrar oranı, kalıcı hata ve iş tamamlama süresidir. Hiçbirini ölçmeden “exactly once” garantisi vermeyin.

• İmzasız veya geçersiz olay reddediliyor.
• Duplicate event için iş etkisi bir kez oluşuyor.
• Worker yeniden başladığında işler toparlanıyor.
• Başarısız replay ve operatör işlemi audit kaydına giriyor.