Webhook Yeniden Deneme Yönetimi: İmza, Kuyruk ve Mükerrer İşlem Kontrolü

Webhook yeniden deneme akışı nasıl kurulmalı?

Webhook yeniden deneme yönetimi, başarısız bir bildirimi tekrar göndermekten ibaret değildir. Güvenilir bir entegrasyon; gelen isteğin kaynağını doğrulamalı, olayı kalıcı biçimde kaydetmeli, aynı olay tekrar geldiğinde iş sonucunu çoğaltmamalı ve tamamlanamayan işleri görünür bir inceleme kuyruğuna taşımalıdır. Böylece bağlantı kesintisiyle veri kaybı, yeniden teslimle mükerrer işlem birbirine karışmaz.

Bu rehber, bot ve harici sistem bağlantılarında bildirim alıcısının güvenilirliğine odaklanır. Reklam olaylarının ölçümde çift sayılmasını veya kullanıcı ödeme ekranının kurtarılmasını ele almaz. Buradaki problem, kaynak sistemin gönderdiği bir olayın alıcıda doğru ve izlenebilir biçimde işlenmesidir. Teslim kuralları sağlayıcıya göre değiştiğinden tek bir yeniden deneme süresini bütün sistemlere uygulamak doğru bir başlangıç değildir.

Önce olay ve teslim kavramlarını ayırın

Bir olay, kaynak sistemde gerçekleşen değişikliği temsil eder. Teslim ise bu olayın alıcınıza ulaştırılması girişimidir. Aynı olay için farklı zamanlarda birden fazla teslim yapılabilir. İşletme açısından önemli olan, teslim sayısı değil beklenen iş sonucunun doğru oluşmasıdır. Bu nedenle kayıt modeli yalnızca HTTP isteğinin zamanını değil, kaynak olayın kimliğini de taşımalıdır.

Örneğin dış sistemdeki bir kayıt güncellemesi bot üzerinden ekip bildirimi oluşturuyorsa, bağlantı zaman aşımı sonrası gelen tekrarın ikinci bir bildirim üretip üretmemesi açık bir kural olmalıdır. Bu örnek bir tasarım senaryosudur; bütün sağlayıcıların aynı kimlik alanını kullandığı anlamına gelmez. Olay kimliğinin kapsamını, sağlayıcı hesabını ve olay türünü entegrasyon belgesinden doğrulayın.

İmza doğrulamasını iş mantığından önce yapın

Bir isteğin belirlenen adrese ulaşması, güvenilir kaynaktan geldiğini kanıtlamaz. Sağlayıcı imza doğrulaması sunuyorsa resmî yöntemi uygulayın ve doğrulanmayan isteği işleme almayın. GitHub'ın webhook rehberi, kaynak doğrulaması için webhook sırrı kullanılmasını ve hassas bilgilerin bildirim URL'sine eklenmemesini önerir.

Anahtarı kod deposuna, kullanıcı arayüzüne veya ayrıntılı hata çıktısına koymayın. Gizli değerin değiştirilmesi gerektiğinde geçişin nasıl yapılacağını teknik planın parçası haline getirin. Test ve canlı ortamların yapılandırmasını ayırın. Hangi isteğin reddedildiğini izleyebilirsiniz, ancak bunu yaparken müşterinin tüm verisini veya doğrulama sırrını kayda almak zorunda değilsiniz.

Ham veri ve dönüşüm sırası

Bazı sağlayıcılarda imza kontrolü gelen isteğin özgün gövdesine dayanır. Aradaki yazılım katmanlarının gövdeyi değiştirmesi doğrulama sorununa yol açabilir. Bu davranışı kullanılan sağlayıcının belgesinden doğrulayın; bütün sistemlerde aynı algoritma veya başlık adını beklemeyin. Hata çözümünde ilk adım, resmî örnek ile gerçek isteğin alıcınıza ulaştığı biçimi güvenli şekilde karşılaştırmaktır.

Alındı yanıtı ile işin bitmesini ayırın

Webhook alıcısı ağır işlerin tamamını isteğin içinde yaparsa yanıt gecikebilir. GitHub rehberi, zamanında yanıt için olayların kuyruk üzerinden arka planda işlenmesini önerir. Bu yaklaşımı kullanırken, başarılı yanıt vermeden önce olayın güvenilir biçimde teslim alındığını kanıtlayacak bir kayıt veya kuyruk kabulü bulunmasını planlayın. Aksi halde başarı yanıtından sonra kaybolan veri kaynak sistem açısından görünmez kalabilir.

Kuyruk tasarımı da işin otomatik olarak tamamlanacağını garanti etmez. Çalışan süreç durabilir, hedef servis erişilemez olabilir veya kayıt biçimi beklenen yapıya uymayabilir. “Alındı”, “işleniyor”, “tamamlandı” ve “inceleme gerekiyor” durumlarını ayırmak yararlı bir modeldir. İşletme paneli yalnızca yeşil bir bağlantı simgesi yerine çözülmemiş olayları göstermelidir.

Aynı olayın etkisini çoğaltmayın

İdempotent işlem, aynı olayın yeniden işlenmesinin istenmeyen ek sonuç üretmemesi hedefidir. Bunun için sadece bellekte tutulan bir liste yerine kalıcı kayıt ve eşzamanlı işlem kontrolü değerlendirilmelidir. Olay kimliğini kontrol edip daha sonra kaydetmek arasındaki boşlukta başka bir çalışan da aynı olayı alabilir. Teknik ekip bu yarışı veri katmanı ve işlem sınırlarıyla çözmelidir.

Stripe webhook belgesi, aynı olayın birden fazla kez ulaşabileceğini ve işlenmiş olay kimliklerinin izlenmesini açıklar. Bu sağlayıcı örneği, her bağlantının aynı yeniden deneme takvimini kullandığını göstermez. Entegrasyonunuzda olay kimliği ile iş kaydının ilişkisini ayrıca tanımlayın; bir teslim tekrarıyla gerçekten yeni bir iş olayını yanlışlıkla birleştirmeyin.

Bildirim gönderme gibi dış yan etkiler için de ayrı kontrol gerekir. Veritabanı kaydı tamamlandığı halde mesaj gönderimi başarısız olmuşsa bütün işlemi baştan yapmak doğru seçenek olmayabilir. Hangi adımın tamamlandığını kaydedip yalnızca eksik adımı yeniden denemek, değerlendirilmesi gereken bir tasarım yaklaşımıdır. Bu davranışın testlerle kanıtlanması gerekir.

Yeniden deneme ve inceleme yolunu ayırın

Geçici bağlantı hatasıyla kalıcı veri hatası aynı şekilde ele alınmamalıdır. Erişim problemi çözülebilirken, eksik bir zorunlu alan tekrar gönderilince kendiliğinden düzelmeyebilir. Sınırsız tekrar yerine hata sınıfı, bekleme politikası ve incelemeye aktarım koşulu belirleyin. Sağlayıcının otomatik teslim davranışını ve sizin iç kuyruğunuzun tekrarlarını birbirinden ayırın.

Başarısız işlerin ayrıldığı inceleme kuyruğunda neden, son deneme ve sorumlu ekip görülebilmelidir. Elle yeniden çalıştırma yetkisini sınırlayın ve yapılan işlemi kaydedin. Bir operatör aynı olayı tekrar başlattığında tekilleştirme kontrolleri devre dışı kalmamalıdır. Aksi halde teknik koruma, yönetim panelinden yapılan müdahaleyle aşılmış olur.

Olayların sıralı geleceğini de varsaymayın. Stripe belgesi teslim sırasının garanti edilmediğini belirtir. Kaynak kaydın güncel halini kontrol etme veya sürüm bilgisini değerlendirme gibi yöntemler, iş gereksinimine göre seçilebilir. Eski bir olayın yeni durumu geri çevirmemesi için kabul koşulunu açıkça yazın.

Kabul testleri nasıl hazırlanır?

Testler yalnızca geçerli bir olayın bir kez gönderilmesini kapsamamalıdır. Aynı olayın eşzamanlı teslimi, yanıtın kaybolması, çalışan sürecin durması ve hedef servisin hata vermesi ayrı senaryolar olarak denenmelidir. Test ortamında gerçek müşteri mesajı göndermek yerine kontrollü hedefler kullanın. Her testte hem olay kaydını hem oluşan iş sonucunu inceleyin.

Kabul listesine şu soruları ekleyebilirsiniz:

• Geçersiz imzalı istek iş sonucu oluşturuyor mu?
• Aynı olay yeniden geldiğinde ikinci kayıt veya mesaj oluşuyor mu?
• Kuyruk erişilemezken alıcı yanlış başarı yanıtı veriyor mu?
• Kalıcı hata anlaşılır bir inceleme kaydı üretiyor mu?
• Elle tekrar işlemi yetki kontrolünden geçiyor mu?
• Eski olay güncel veriyi beklenmedik şekilde değiştiriyor mu?

İşletmeniz için entegrasyon kapsamı

Webinle'nin bot yazılımları ve entegrasyon hizmeti üzerinden bağlı sistemlerinizi, olay türlerini ve hata senaryolarını değerlendirebilirsiniz. Entegrasyonun kullanıcı talebi tarafını ele almak için CRM bağlantılı teklif formu rehberini inceleyin. İyi bir teslim planı, kesintiyi gizlemek yerine sorunu görünür kılar ve kontrollü biçimde çözme yolu sunar.