Dayanıklı Webhook ve Kuyruk Mimarisi

n8n, Make, Zapier veya benzeri platformlarda webhook’tan gelen isteği doğrudan birden fazla dış servise iletmek yerine doğrulama, tekilleştirme ve kuyruk adımlarından geçirin. Böylece kısa süreli kesintiler, yoğun trafik ve rate limit aşımı tüm akışı durdurmaz.

Önerilen akış:

• HTTP yöntemi, içerik türü, imza ve zorunlu alanları doğrulayın.
• Gelen veriden yalnızca akışın ihtiyaç duyduğu alanları ayırın.
• Benzersiz bir event_id ve izleme için bir correlation_id üretin veya sağlayıcının kimliğini koruyun.
• Olayı “alındı” durumuyla kuyruğa ya da bekleyen kayıt deposuna yazın.
• Kuyruktan kontrollü hızda alıp dış servislere gönderin.

Webhook yanıtını uzun süren işlemin sonucunu bekletmek yerine hızlı bir kabul yanıtı olarak tasarlayın. Nihai durumu bir durum alanı, bildirim veya geri çağırma akışıyla takip edin. Kuyruğa yazma başarısızsa başarılı kabul yanıtı vermeyin; aksi durumda olay kaybolabilir.

Idempotency ve Güvenli Yeniden Çalıştırma

Webhook sağlayıcıları aynı olayı ağ hatası veya zaman aşımı nedeniyle tekrar gönderebilir. Her olay işlenmeden önce event_id için daha önce tamamlanmış, işleniyor veya başarısız bir kayıt bulunup bulunmadığını kontrol edin. Aynı kimlik daha önce tamamlandıysa işlemi yeniden başlatmak yerine mevcut sonucu döndürün.

Dış serviste destekleniyorsa idempotency anahtarını istek başlığına veya ilgili alana taşıyın. Desteklenmiyorsa işlem öncesi kayıt kontrolü, benzersiz anahtar ve durum geçişleri kullanın. “İşleniyor” durumunda kalan kayıtlar için zaman aşımı belirleyin; ancak eski işlemin hâlâ devam etmediğini doğrulamadan ikinci kez çalıştırmayın.

Örneğin ödeme, e-posta veya stok güncellemesi gibi yan etkili adımlarda şu ayrımı koruyun:

• Olay alındı: Kuyruğa yazıldı.
• İşleniyor: Dış servise gönderim başladı.
• Tamamlandı: Sonuç ve dış servis kimliği kaydedildi.
• Yeniden denenebilir hata: Kontrollü tekrar bekliyor.
• Kalıcı hata: Hata kuyruğuna taşındı.

Rate Limit ve Hata Yönetimi

Her dış API için kota, pencere süresi, eşzamanlı istek sınırı ve hata yanıtlarını belgeleyin. Sabit aralıklarla sınırsız tekrar yapmak, geçici sorunu daha büyük bir kesintiye dönüştürür.

• 429 yanıtında servis tarafından verilen Retry-After bilgisini kullanın.
• 5xx, bağlantı ve zaman aşımı hatalarında üstel bekleme ve küçük bir rastgele sapma uygulayın.
• Geçersiz kimlik doğrulama, hatalı istek veya yetki reddi gibi 4xx hatalarını otomatik tekrar etmeyin.
• Maksimum deneme sayısına ulaşan kayıtları hata kuyruğuna taşıyın.
• İşçi sayısını ve paralel dallanmayı sağlayıcının kapasitesine göre sınırlayın.

Her denemede durum, hata sınıfı, bekleme süresi ve deneme sayısını kaydedin. Aynı anda açılan istek sayısını ayrıca izleyin; toplam günlük kota uygun olsa bile ani paralellik rate limit tetikleyebilir.

Veri Gizliliği ve Veri Minimizasyonu

Webhook gövdesindeki her alanı otomasyon platformuna taşımayın. Kimlik, adres, telefon, erişim belirteci ve müşteri notu gibi hassas verileri yalnızca ihtiyaç duyan adıma aktarın. Mümkünse dış servise ayrıntılı kişisel veri yerine dahili kayıt kimliği gönderin ve ayrıntıları kontrollü bir backend adımından sağlayın.

Uygulama öncesi şu kontrolleri yapın:

• Gereksiz alanlar akışın ilk adımında çıkarılıyor mu?
• Loglarda token, parola, kişisel veri veya tam istek gövdesi maskeleniyor mu?
• Üçüncü taraf modüller hangi verileri alıyor ve ne kadar süre saklıyor?
• Kimlik bilgileri düz metin yerine platformun güvenli bağlantı veya gizli değişken alanlarında mı tutuluyor?
• Hata kuyruğunda hassas veri birikmesini önlemek için maskeleme veya saklama süresi uygulanıyor mu?

Test ve geliştirme ortamında gerçek müşteri verisi kullanmayın. İstek imzası doğrulamasını, TLS kullanımını ve webhook yeniden oynatma riskini de kontrol edin.

İzleme, Bakım ve Operasyon Kontrol Listesi

Her işlem için en az işlem kimliği, korelasyon kimliği, başlangıç ve bitiş zamanı, son durum, deneme sayısı, hata sınıfı ve dış servis yanıt kimliğini tutun. Bu bilgiler başarısız kayıtları güvenle yeniden çalıştırmayı ve kullanıcıya doğru durum vermeyi sağlar.

Akışın yanında kısa bir çalışma notu bulundurun:

• Webhook sözleşmesi ve örnek istek.
• Kullanılan servisler, kota bilgileri ve beklenen yanıtlar.
• Yeniden çalıştırmanın güvenli olup olmadığı.
• Hata kuyruğunun sahibi ve hedef çözüm süresi.
• Kimlik bilgisi, alan adı veya API sürümü değiştiğinde izlenecek adımlar.

Haftalık veya sürüm değişikliği öncesinde kontrollü test olayları gönderin: başarılı işlem, 429 yanıtı, geçersiz veri, zaman aşımı, aynı olayın ikinci kez gelmesi ve dış servisin 5xx dönmesi. Kuyruk uzunluğu, hata oranı, tekrar deneme sayısı ve en eski bekleyen kaydı izleyin. Yeni adım eklemeden önce veri akışının, hata yönetiminin ve yeniden çalıştırma davranışının ekip tarafından hâlâ anlaşılır olduğundan emin olun.