Laravel webhook endpoint’ini yerelde 422 → 200 ile sına

Önkoşullar

Laravel 13.x projenin Composer platform gereksinimleri karşılanmalı; php --version ve php artisan --version ile kullandığın CLI’ı kontrol et. Buradaki HTTP akışı izole Laravel 13.38.0 / PHP 8.5.11 fixture’ında sınandı. Bu sonuç LocalTR public tüneli veya sağlayıcı entegrasyonu kabulü değildir. Yerel testi LocalTR kurmadan yapabilir, uygulama adımlarını kullanılabilir Mac sürümü ve gerekli izinlerle ayrıca doğrulayabilirsin.

Yalnız local ortamda test route’u ekle

routes/web.php içine kendi test projen için şu route’u ekle. Ortam koşulunu kaldırma; production ortamında bu örnek route tanımlanmaz:

use Illuminate\Http\Request;
use Illuminate\Support\Facades\Route;

if (app()->environment('local')) {
    Route::post('/webhooks/localtr-demo', function (Request $request) {
        abort_unless($request->isJson(), 415);
        abort_if(strlen($request->getContent()) > 4096, 413);
        $request->validate([
            'event' => ['required', 'in:payment.test'],
            'currency' => ['required', 'in:TRY'],
        ]);
        return response()->json(['status' => 'received']);
    });
}

Bu handler yalnız kurgusal test olayını doğrular; ödeme, sipariş, e-posta veya kalıcı kayıt üretmez. Gerçek endpoint’in imza doğrulamasını bununla değiştirme.

CSRF istisnasını tek URI ile sınırla

Laravel 13’te bootstrap/app.php içindeki mevcut withMiddleware bloğuna yalnız şu URI’ı ekle; diğer ayarları koru:

$middleware->preventRequestForgery(except: ['webhooks/localtr-demo']);

* kullanma, bütün web grubunu korumasız bırakma. Route yalnız local ortamda kayıtlı kalmalı; örnek route’u kaldırdığında bu istisnayı da kaldır. Bu istisna sağlayıcı kimliğini doğrulamaz. Laravel’in PHPUnit test modunda CSRF farklı ele alınabildiğinden, aşağıdaki normal HTTP isteğini de kontrol et.

Eksik alanı ve düzeltilmiş isteği gönder

Local ortamındaki projeyi php artisan serve --host=127.0.0.1 --port=8000 ile başlat. Ayrı terminalde:

curl -i http://127.0.0.1:8000/webhooks/localtr-demo \
  -H 'Accept: application/json' -H 'Content-Type: application/json' \
  --data '{"event":"payment.test"}'

Beklenen 422 ve JSON içindeki errors.currency alanıdır. Aynı komutta gövdeyi yalnız {"event":"payment.test","currency":"TRY"} olarak değiştir; beklenen 200 ve {"status":"received"} olur. Accept: application/json olmadan hata yanıtının biçimi farklı olabilir. Bu örnek tekrar gönderildiğinde yeni iş kaydı oluşturmaz; gerçek POST endpoint’lerinde yan etki ve deduplikasyon ayrıca değerlendirilir.

Sorun giderme, güvenlik ve sonraki adım

419 görürsen istek URI’ını ve dar CSRF istisnasını karşılaştır; korumayı topluca kapatma. 404 için ortamı ve php artisan route:list --path=webhooks çıktısını kontrol et. 422 için JSON alanlarını incele; 405 için POST kullandığını doğrula. Gerçek sır, oturum veya müşteri verisi gönderme. Sağlayıcı imzaları özgün ham gövdeye bağlı olabilir; gövdeyi değiştirince eski imzanın geçerli kalacağını varsayma.

Resmî kaynaklar: Laravel routing, CSRF ve validation. Sonraki adım webhook/replay rehberindeki hedef kontrolüdür; uygulama Replay gerçek istek gönderir. Paket olmadan yalnız metni incelemek için HTTP örnek aracını kullanabilirsin.

Laravel projesi kullanmadan aynı 422 → 200 ayrımını denemek istersen bağımsız Node.js webhook örneğini çalıştırabilirsin. Bu yerel test public tünel veya sağlayıcı kabulü değildir.