Webhookları Anlamak ve Güvenlik Altına Almak

Bir webhook özünde n8n sisteminize açılan bir kapıdır: harici bir hizmet, Webhook düğümü tarafından oluşturulan URL'ye bir HTTP isteği gönderir göndermez, ilgili iş akışı herhangi bir zamanlama olmadan ve manuel tıklama gerekmeden otomatik olarak başlar. Tam da bu açıklık, webhookları Stripe, GitHub, form araçları veya kendi uygulamalarınızla entegrasyonlar için bu kadar kullanışlı kılar. Ancak kimlik doğrulama, IP filtresi ve imza kontrolü araya girmediğinde URL'yi bir saldırı noktasına da dönüştürür. URL'yi bilen veya tahmin eden herkes iş akışını tetikleyebilir.

Bu makale, n8n'deki Webhook düğümünün yapısını, yerleşik kimlik doğrulama yöntemlerini, ek bir koruma katmanı olarak IP beyaz listesini ve kendi barındırılan n8n örneklerinde düzenli olarak kafa karışıklığına yol açan bir konu olan reverse proxy arkasındaki yapılandırmayı gösterir. Güncelleme: Temmuz 2026.

Webhook düğümünün yapısı nasıldır

Şu kaynağa göre, n8n Webhook düğümü dokümantasyonu, düğüm altı HTTP yöntemini destekler: DELETE, GET, HEAD, PATCH, POST ve PUT. Path alanında URL'nin yolunu belirlersiniz, bunu serbestçe veya dinamik segmentler için `/:variable` gibi yer tutucularla yapabilirsiniz. Kendi girdiniz olmadan n8n rastgele bir yol oluşturur, bu da diğer iş akışlarıyla çakışmaları önler.

Yanıt için birkaç seçenek vardır:

• Immediately: Webhook, iş akışının sonunu beklemeden, iş akışının başladığını bildiren mesajla hemen yanıt verir.
• When Last Node Finishes: Yanıt, çalıştırılan son düğümün verilerini içerir.
• Using Respond to Webhook Node: İş akışındaki ayrı bir düğüm, yanıtın durum kodunu, başlıklarını ve gövdesini özel olarak kontrol eder.
• Streaming response: Akış (streaming) destekleyen düğümler için yanıt gerçek zamanlı olarak iletilebilir.

Pratikte önemli olan: dokümantasyona göre n8n aynı anda yalnızca bir yol ve HTTP yöntemi kombinasyonunu kaydeder. Aynı yola ve aynı yönteme sahip iki aktif iş akışı birbirini engeller; birinin devre dışı bırakılması veya yolun ya da yöntemin değiştirilmesi gerekir.

Doğrudan Webhook düğümünde kimlik doğrulama

IP filtreleri veya reverse proxy kuralları hakkında düşünmeden önce, Webhook düğümünün yerleşik kimlik doğrulamasını kullanmalısınız. Şu kaynağa göre, Webhook kimlik bilgileri dokümantasyonu dört seçenek mevcuttur:

• Basic Auth: Çağıran hizmet, Authorization başlığında bir kullanıcı adı ve şifre göndermelidir. Kurulumu kolaydır, ancak ek bir şifreleme sağlamadığından yalnızca HTTPS ile birlikte anlamlıdır.
• Header Auth: Örneğin `X-API-Key` gibi bir başlık adı ve gizli bir değer belirlersiniz. n8n her gelen isteği tam olarak bu başlık için kontrol eder. Bu yöntem zaten bir API anahtarı gönderen hizmetlere iyi uyar.
• JWT Auth: İsteğin dijital olarak imzalanmış bir JSON Web Token içermesi gerekir. n8n imzayı, kimlik bilgisinde sakladığınız bir parola veya bir PEM anahtarı üzerinden doğrular.
• None: Kontrol yapılmaz, doğru yola sahip her istek kabul edilir. Bu ayar en fazla kısa testler için uygundur, üretim iş akışları için değil.

Dokümantasyon önemli bir noktayı açıkça belirtir: seçilen yöntem, çağıran hizmetin fiilen gönderdiği şeyle eşleşmelidir. Örneğin bir GitHub webhook'u genellikle istekleri başlıkta bir HMAC imzasıyla imzalar; düğüm kimlik doğrulamasının ötesinde güvenlik sağlamak istiyorsanız bunu Header Auth'a ek olarak bir Code düğümünde kontrol edebilirsiniz.

Ek bir koruma katmanı olarak IP beyaz listesi

Kimlik doğrulamaya ek olarak, Webhook düğümü IP(s) Whitelist seçeneğini sunar. Buraya virgülle ayrılmış izin verilen IP adresleri listesi girersiniz; dokümantasyona göre n8n, listede olmayan adreslerden gelen isteklere 403 hatasıyla yanıt verir. Alan boş bırakılırsa tüm adreslere izin verilir.

Pratikte IP beyaz listesi, tek başına bir koruma olarak değil, Header Auth veya JWT Auth'un yanında ikinci bir katman olarak en iyi şekilde çalışır: Stripe veya GitHub gibi bir hizmetin sabit gönderen IP aralıkları varsa, bunları girersiniz ve böylece diğer her şeyi baştan engellersiniz. Değişen veya belirsiz IP aralıklarına sahip hizmetlerde başlık veya JWT kontrolü daha güvenilir yöntem olmaya devam eder. Böylece asıl mantık çalışmaya başlamadan önce iş akışına kimin ulaşabileceği üzerinde kontrolü elinizde tutarsınız.

Webhookları bir reverse proxy arkasında doğru şekilde yapılandırmak

n8n, örneğin Caddy, Nginx veya Traefik gibi bir reverse proxy arkasında kendi kendine barındırıldığında, otomatik URL algılama artık güvenilir şekilde çalışmaz: n8n dahili olarak genellikle 5678 portunda çalışırken, proxy uygulamayı dışarıya 443 portu üzerinden gösterir. Şu kaynağa göre, n8n'in reverse proxy arkasında webhook URL yapılandırmasına ilişkin dokümantasyonu bunu iki ortam değişkeniyle çözersiniz:

• WEBHOOK_URL: n8n'in editörde gösterdiği ve harici hizmetlere kaydettiği tam, herkese açık olarak erişilebilir adresi belirler, örneğin `https://n8n.ornek.com/`.
• N8N_PROXY_HOPS: Önceden bağlı proxy sayısına ayarlanmalıdır, genellikle 1. Bu sayede n8n, bir proxy tarafından iletilen başlıkları doğru şekilde yorumlar.

Proxy'nin kendisi, `X-Forwarded-For`, `X-Forwarded-Host` ve `X-Forwarded-Proto` başlıklarını iletmelidir. Bu yapılandırma eksikse, önceki bölümdeki IP beyaz listesi etkisiz kalabilir; çünkü n8n bu durumda gerçek gönderen IP'si yerine yalnızca proxy'nin dahili adresini görür. n8n dokümantasyonuna göre tam olarak bu ilişki en yaygın hata kaynaklarından biridir: liste doğru şekilde tutulsa bile, N8N_PROXY_HOPS eksik veya yanlış ayarlandığı için beyaz listedeki IP'ler reddedilir.

Test ve üretim URL'sini karıştırmamak

Her Webhook düğümü iki farklı URL oluşturur. Test URL'si, düğümde Listen for Test Event'e tıkladığınızda gelen verileri editörde gösterir, ancak dokümantasyona göre yalnızca 120 saniye aktif kalır. Üretim URL'si yalnızca iş akışı yayınlandığında devreye girer, ancak o zaman verileri artık editörde değil, yalnızca Executions sekmesinde gösterir.

Pratikte tipik bir hata: harici bir hizmet, editörde görünür geri bildirim sağladığı için geliştirme sırasında test URL'sine yapılandırılır. İş akışı yayınlandıktan sonra webhook boşa çalışır, çünkü hizmet hâlâ üretim URL'si yerine eski test URL'sine istek gönderir. Bu nedenle her canlıya geçişten önce, çağıran sistemde gerçekten üretim URL'sinin kayıtlı olup olmadığını kontrol edin. n8n'i kendi kendine barındırılan dijital bir çalışan olarak kullanan ve temiz, izlenebilir webhook güvenliğine önem veren kişiler, NordFlux'un n8n danışmanlığında kurulum, kimlik doğrulama ve reverse proxy yapılandırması konusunda destek bulur.

Sık sorulan sorular

Bir webhook'u güvence altına almak için tek başına Header Auth yeterli midir?

Birçok dahili otomasyon için, gizli değer yeterince uzun ve tahmin edilemezse HTTPS üzerinden Header Auth yeterlidir. Ödeme sağlayıcıları gibi güvenlik açısından kritik entegrasyonlarda, ek olarak IP beyaz listesi veya sonraki bir Code düğümünde HMAC gibi bir imza kontrolü önerilir.

Beyaz listeye eklediğim IP adresim neden yine de engelleniyor?

Bu genellikle n8n bir reverse proxy arkasında çalışırken eksik veya yanlış ayarlanmış bir N8N_PROXY_HOPS'tan kaynaklanır. Bu değişken olmadan n8n, gerçek gönderen IP'sini değil, proxy'nin dahili adresini görür ve bunu yanlışlıkla beyaz listeyle karşılaştırır.

Aynı webhook yoluna birden fazla iş akışı koyabilir miyim?

Hayır, n8n dokümantasyonuna göre bir yol ve HTTP yöntemi kombinasyonu başına aynı anda yalnızca bir webhook kaydedilebilir. Aynı yol üzerinde birden fazla tetikleyici için farklı HTTP yöntemleri kullanmanız veya yolu uyarlamanız gerekir.

Geliştirme sonrasında test URL'sini kullanmaya devam edersem ne olur?

Test URL'si, Listen for Test Event'e tıklandıktan sonra yalnızca 120 saniye aktiftir ve verileri editörde gösterir. İş akışı yayınlandıktan sonra çağıran sistemlerin üretim URL'sine geçirilmesi gerekir, aksi takdirde istekleri boşa gider.

Çağıran hizmet sunmuyorsa JWT Auth kullanmam gerekir mi?

Hayır, kimlik doğrulama yöntemi her zaman çağıran hizmetin fiilen desteklediği şeye bağlıdır. Bir hizmet yalnızca basit bir API anahtarı sunuyorsa, imzalı bir token gerektiren JWT Auth'tan daha uygun olan Header Auth'tur.