Webhook hatasını yeniden üretilebilir hale getir

Bir webhook sağlayıcısının panelinde “teslim edilemedi” yazması, hatanın nerede olduğunu söylemez. İstek uygulamana hiç ulaşmamış olabilir. Yanlış path'e gitmiş, imza kontrolünden dönmüş veya başarılı işlenip geç yanıt vermiş olabilir. İlk amaç tekrar tekrar denemek değil, hangi isteğin hangi yanıtı ürettiğini görünür kılmaktır.

Bağlantı ile iş mantığını ayır

Önce kendi test endpoint'inin yerel adresten yanıt verdiğini doğrula. Sonra public bağlantıyı farklı bir ağdan dene. Bu iki adım geçmeden sağlayıcının tekrar gönderme düğmesine basmak fazla bilgi sağlamaz. Public URL'nin Mac, LocalTR ve geliştirme sunucusu açıkken çalıştığını da unutma.

LocalTR'nin inspector görünümünde metot, path, başlıklar, gövde, yanıt ve süre birlikte incelenebilir. Kaydı sağlayıcının teslimat zamanı ve olay kimliğiyle eşleştir. İki farklı olayı aynı “başarısız istek” gibi ele almak yanlış bir düzeltmeye götürebilir. Örnek veride açık bir test kimliği kullanmak, gözlemi kolaylaştırır.

Durum kodunu bağlamıyla oku

401, public bağlantının parolasından veya uygulamanın kendi yetkilendirmesinden gelebilir. 503, paylaşımın duraklatılmış olmasıyla ilgili olabilir. Bir 200 ise iş mantığının doğru sonuçlandığını tek başına kanıtlamaz; uygulama yanıtı erken dönmüş ve sonraki işlem başarısız olmuş olabilir.

Bu nedenle yalnız durum kodunu kopyalamak yerine hedef path'i, yaklaşık zamanı ve beklenen uygulama sonucunu kaydet. Gerekirse uygulamanın test veritabanında ilgili test olayını incele. Gerçek ödeme veya sipariş kaydı üretmek hata ayıklamanın zorunlu parçası değildir; kontrollü bir test hedefi daha güvenilir kanıt sağlar.

Replay gerçek bir istektir

LocalTR'de gerçek yeniden gönderme yolu isteğin detay panelindeki Replay eylemidir. Burada hedefi, başlıkları ve gövdeyi düzenleyip onaylarsın; yeni yanıt yeni capture kaydı oluşturur. Liste bağlam menüsündeki Replay aynı tamamlanmış akış değildir.

Göndermeden önce URL'ye tekrar bak. Yerel test endpoint'i yerine canlı servisi hedefleyen kayıt, ikinci bir e-posta veya başka bir yan etki doğurabilir. Tek bir alanı değiştirerek ilerlemek, hangi değişikliğin sonucu etkilediğini anlamayı da kolaylaştırır. Orijinal kayıt ile yeni isteği ayrı tut; yeniden gönderilen isteğin gerçekten sağlayıcıdan geldiğini varsayma.

Aynı test olayını tek değişiklikle izle

Aşağıdaki HTTP mesajları yazı için hazırlanmış kontrollü örneklerdir. Ağdan alınmış capture veya kabul edilmiş LocalTR sürümü sonucu değildir. Yalnız kendine ait, ödeme/e-posta/harici webhook üretmeyen test handler’ında dene.

Çalıştırılabilir ayrı bir örnek için yerel webhook starter'ını aç. Starter, /webhook üzerinde event: payment.test ve currency kullanır; aşağıdaki /hooks/demo ve mode örneğinin uygulaması değildir.

Özgün örnekte mode alanı bu hayalî test handler’ının kabul ettiği değerden farklıdır:

POST /hooks/demo HTTP/1.1
Host: localhost:3000
Content-Type: application/json

{"id":"evt_demo_001","type":"demo.updated","mode":"before"}

HTTP/1.1 422 Unprocessable Content
Content-Type: application/json

{"error":"invalid_mode","id":"evt_demo_001"}

Detay panelinde Replay açıldığında önce hedefin hâlâ kendi test endpoint’in olduğunu kontrol et. Yalnız mode değerini after olarak değiştir. Olay kimliğini ve özgün kaydı notunda koru:

{"id":"evt_demo_001","type":"demo.updated","mode":"after"}

Bu örnek handler için beklenen yeni yanıt 200 OK ve {"accepted":true,"id":"evt_demo_001"} olur. Gerçekte dönen durum, yeni capture ve uygulamanın test kaydı görülmeden “düzeldi” sonucuna varılmaz. İmza kontrolü kullanan gerçek sağlayıcının olayını bu imzasız örnekle aynı sayma.

MDN POST belgesi, aynı POST’un tekrarının ek etki oluşturabileceğini açıklar. Sağlayıcının yeniden teslimi de uygulamanın kendi deduplikasyonunu gerektirebilir. Örneğin Stripe’ın webhook belgesi işlenen olay kimliklerini izlemeyi önerir; imza kontrolünde özgün ham gövde gerekir. Bu teknik kaynak, LocalTR’nin ödeme sağlayıcısı olduğu veya entegrasyonunun kabul edildiği anlamına gelmez.

İmza ve maskeleme neden önemlidir?

Sağlayıcının imzası özgün ham gövdeye ve zamana bağlı olabilir. Gövdeyi değiştirince aynı imza geçersiz hale gelebilir. Doğru çözüm üretim imza kontrolünü kapatmak değildir. Sağlayıcının test ortamını ve kendi doğrulama mantığını kullanarak beklenen reddi veya kabulü açıklayabilmelisin.

Inspector bazı hassas başlıkları ve belirli JSON/form alanlarını saklanan kopyada maskeler. Bu alanlar replay sırasında kendiliğinden geri gelmez. Öte yandan query parametreleri veya serbest metindeki her sırın bulunduğu garanti değildir. Kayıt güvenli görünse bile paylaşmadan önce incele. Kullanıcı verisi, token ve oturum çerezi destek mesajına taşınmamalı.

Saklama geçmişi bir arşiv değildir

Kaynakta capture deposu 10.000 kayıt sınırı, bellek bütçesi ve açılışta 1.000 kayıt geri yükleme sınırı tanımlar. İnceleme için bellekte tutulan gövde de sınırlıdır. Eksik bir gövdeyi sağlayıcının boş gönderdiği sonucuna hemen bağlama. Önce capture sınırını ve uygulamanın kendi test logunu karşılaştır.

İyi bir hata kaydı şu dört parçayı bir arada tutar: temizlenmiş özgün istek, beklenen sonuç, tek değişiklikle yapılan replay ve gerçek uygulama sonucu. Böylece düzeltmeyi tekrar sınayabilir ve aynı hatanın dönüp dönmediğini anlayabilirsin. Uygulamadaki adımlar webhook ve replay rehberinde; erişim sorunu varsa önce public URL koşullarını kontrol et.