Webhook’lar harikadır, ta ki hedef sunucunuz çökene veya ağ bağlantısı kopana kadar. Webhook doğası gereği “gönder ve unut” (fire and forget) prensibine yakın çalışır, ancak kritik iş süreçlerinde (ödeme alma gibi) “unutmak” bir seçenek değildir.

Bu yazıda, webhook mimarinizi nasıl daha dayanıklı (resilient) hale getirebileceğinizi ve veri kaybını nasıl %0’a indirebileceğinizi inceleyeceğiz.

1. Timeout Yönetimi (Zaman Aşımı)

Webhook gönderen servis, sonsuza kadar yanıt beklemez. Genellikle 5-10 saniyelik bir zaman aşımı süresi vardır. Eğer endpoint’iniz bu sürede yanıt vermezse, istek başarısız sayılır.

Çözüm: Webhook’u karşılayan endpoint’inizde asla uzun süren işlemler (PDF oluşturma, mail atma, veritabanı raporlama) yapmayın. Yapmanız gereken tek şey:

İsteği al.
Kuyruğa at (Queue).
Göndericiye 200 OK dön.
İşlemi arka planda (Background Worker).

2. Retry Mekanizması (Yeniden Deneme)

Her sistem çökebilir. Sunucunuz bakımda olabilir veya anlık bir ağ hatası yaşanabilir. Bu durumlarda webhook’un kaybolmaması gerekir.

Exponential Backoff: Başarısız olan bir isteği hemen tekrar denemek yerine, bekleme süresini artırarak denemek en sağlıklı yöntemdir.

1. Deneme: Hata
1. Deneme: 5 saniye sonra
1. Deneme: 30 saniye sonra
1. Deneme: 5 dakika sonra

Webhook sağlayıcınızın (örneğin Stripe) retry politikasını mutlaka inceleyin. Kendi webhook gönderimlerinizde de mutlaka bir retry stratejisi kurgulayın.

3. Idempotency (Tekrarlanabilirlik)

Retry mekanizması harikadır ama tehlikeli bir yan etkisi vardır: Aynı isteğin birden fazla kez gelmesi. Ağ hatası yüzünden 200 OK yanıtı göndericiye ulaşmazsa, gönderici aynı webhook’u tekrar yollar. Eğer kodunuz buna hazırlıklı değilse, müşteriden iki kez ödeme çekebilir veya veritabanına mükerrer kayıt atabilirsiniz.

Çözüm: Her webhook isteğinde benzersiz bir ID (Event ID) bulunur. Bu ID’yi veritabanınızda veya Redis’te tutun.

if redis.exists(event_id) {
    return 200 OK; // Zaten işledik, tekrar yapma.
}
process_payment();
redis.save(event_id);

4. Güvenlik ve Doğrulama (HMAC)

Endpoint’iniz public (herkese açık) olduğu için, kötü niyetli kişiler sahte webhook istekleri gönderebilir. Bunu önlemek için HMAC (Hash-based Message Authentication Code) imzasını doğrulamanız şarttır. Gönderici, payload’ı gizli bir anahtarla (secret key) hash’ler ve header’da gönderir. Siz de aynı işlemi yapıp eşleşip eşleşmediğini kontrol edersiniz.

5. Dead Letter Queue (DLQ)

Tüm retry denemeleri başarısız olduysa ne olacak? Veriyi silmek yerine “Dead Letter Queue” (Ölü Mektup Kuyruğu) denilen ayrı bir alana taşıyın. Buradaki hatalı kayıtları daha sonra manuel olarak inceleyebilir ve sorunu çözdükten sonra tekrar işleme alabilirsiniz.

Özet

Güvenilir bir webhook mimarisi kurmak; kuyruk yönetimi, retry stratejileri ve güvenlik önlemleri gerektirir.

Eğer tüm bu altyapıyı (Queue, Retry, DLQ, Logging) sıfırdan kurmak istemiyorsanız, WebhookIO gibi bir Webhook Gateway kullanabilirsiniz. WebhookIO, gelen tüm istekleri sizin yerinize karşılar, kuyruğa alır ve endpoint’iniz hazır olduğunda size güvenle teslim eder.

Webhook İsteklerini Kaybetmemek İçin Kritik Önlemler