Webhook güvenliği: imzalar, tekrarlar ve işlem durumu

Webhook kaynağını doğrulayın, yinelenen teslimatı kontrol edin ve entegrasyon tekrarladığında ya da dış API yanıtı kaybolduğunda iş sonucunu koruyun.

Webhook, dış sürecin değiştiğini uygulamaya bildirir: ödeme tamamlandı, belge erişilebilir oldu veya kayıt güncellendi. Gelen istek, hatasının önemli maliyeti olan eylem başlatabilir. İşleyici göndereni, mesaj bütünlüğünü ve aynı bilginin tekrar alınmasının etkisini ayrı yanıtlamalıdır.

İş verisini değiştirmeden doğrulayın

İmza doğrulama özgün istek baytlarını ve ilgili bağlantının sırrını ister. GitHub belgeleri HMAC doğrulamayı ve güvenli karşılaştırmayı anlatır. JSON'u ayrıştırıp yeniden serileştirmek imzalanan girdiyi oluşturmak için uygun değildir: boşluklar ve alan sırası değişebilir.

İş operasyonuna başlamadan isteği doğrulayın. Uç noktanın istek boyutu ve işlem süresi sınırları da olmalıdır. Geçerli imza, sağlayıcı protokolü altında mesaj bütünlüğünü belirler; olay türü, veri yapısı ve atıfta bulunulan nesnenin sahipliğini doğrulama ihtiyacını kaldırmaz.

Örneğin varsayımsal ödeme işleyicisi siparişi bulmalı ve önerilen durum geçişinin izinli olup olmadığını belirlemelidir. İmzalı olay herhangi siparişi keyfî değiştirme yetkisi vermemelidir. Bu tasarım senaryosudur, belirli müşteri uygulaması iddiası değildir.

Kötü niyetli tekrarları teslimat tekrarından ayırın

Saldırgan önceden yakalanmış imzalı mesajı yeniden gönderebilir. Stripe, imzalanan veriye zaman damgası ekler ve yaşını kontrol etmeyi anlatır. Mekanizma doğru sunucu zamanına ve sağlayıcı protokolüne dayanır. Zaman damgasını imzalamayan başka hizmete uygulandığını varsaymayın.

Gönderen alındı onayını kaçırınca meşru tekrar da olur. GitHub iyi uygulamaları, tekrarı tanımak için teslimat kimliği kullanır. Kimlikleri tutmak yardım eder, ama iş eylemi kendi korumasını ister. Ayrı olaylar aynı temel işlemle ilgili olabilir; bu nedenle işlemin sabit kimliği olmalıdır.

Teslimat kimliğine tanımlı saklama süresi gerekir. İşlemden hemen sonra silmek, sonraki tekrarları yeni gösterir. Her şeyi sonsuza kadar tutmak depolama ve gizlilik yükümlülüğü doğurur. Politikayı sağlayıcının tekrar davranışından ve eylemi yinelemenin sonuçlarından seçin.

Kabul edilen işi onaylamadan önce kalıcı kaydedin

Pratik tasarımlardan biri isteği doğrular, kabul edilen işi kalıcı kaydeder, sonra yürütmeyi işleyiciye devreder. Kaydetmeden sonra onaylayın; aksi hâlde yanıtla yazma arasındaki hata olayı kaybettirebilir. Kuyruk yine depolama hatası yönetimi ve işleme gecikmesi izlemesi ister.

Yararlı işlem durumları kabul edildi, çalışıyor, tamamlandı ve inceleme bekliyor olabilir. Geçişler tekrarları ve eşzamanlı işleyicileri desteklemelidir. Basit kontrol-et-sonra-ekle sırası iki eşzamanlı isteği geçirebilir. Güvenilir tekrar yönetimi için atomik benzersizlik kısıtı ve eşgüdümlü durum değişimi gerekir.

Zor sınır, yanıt kaybolmadan önce başarılı olan dış eylemdir. Önceden tamamlandı demek eylemi kaybettirebilir; sonradan demek tekrarlatabilir. Dış API idempotency anahtarı destekliyorsa işlemin sabit anahtarını yeniden kullanın. Desteklemiyorsa tasarım mutabakat ve açık belirsiz-sonuç durumu ister.

Belirsizlik yaratan sınırları test edin

Kabul senaryoları değişen gövdeyi, geçersiz imzayı, yinelenen olayı ve eşzamanlı teslimatı kapsamalıdır. Kuyruk hatasını, işleyici yeniden başlamasını ve kayıp dış yanıtı da deneyin. Bunlar tek başarılı bildirimden çok daha fazla şey gösterir.

Günlükler olay kimliğini, durumu ve ret nedenini göstermelidir. Tam içerik kişisel veri içerebilir; saklaması ayrı karar ister. Operatör için açıklanmayan teknik yük yerine mutabakatı yapılabilen ve güvenle tekrarlanabilen görev yararlıdır.

API entegrasyonu planlaması, belirsiz sonuçların nasıl ele alınacağını belirlemelidir. Böylece hangi hatanın otomatik kurtarılacağı ve nerede insanın sonucu doğrulaması gerektiği ortaya çıkar.

Kaynaklar 7 Ekim 2026 tarihinde kontrol edildi. Sağlayıcı protokolleri farklıdır. Durum modeli ve kabul senaryoları, somut entegrasyona uyarlanacak yazar önerileridir.

Hizmet işletmesi sistemi pratik bağlam sunar: diğer eşitlemeler yanında, gelen IVR aramasından sonra GoHighLevel potansiyel müşteri kaydı oluşturmayı uyguladım. Sonuç ekibin işlem yapabildiği kayıttır. Yinelenen olay ve veri sahipliği hakkında somut sorular sunar. Açık vaka mesaj taşımasını veya imza doğrulamayı açıklamaz; yazıdaki gereksinimler o projede uygulanmış kontrol sayılmamalıdır.

Belge, CRM ve görev akışı rehberim, sabit kimlikleri ve zaman aşımı sonrası tekrarları inceler. İmza gereksinimleriyle birlikte okuyun: göndereni belirlemek ve tek iş sonucunu korumak ayrı kontroller ister.