Webhook adresi bir kapı gibi. Adresi bilen herkes ona istek atabilir. Meta'nın mesaj olaylarını gönderdiği adresi doğrulamazsanız, birisi "müşteri sipariş verdi" ya da "ödeme onaylandı" diyen sahte bir olay gönderdiğinde akışınız bunu gerçek sayar. Meta bunun için her isteğe bir imza ekliyor. Bu yazıda o imzanın ne olduğunu ve n8n'de nasıl kontrol edileceğini anlatıyoruz. Türkçe kaynaklarda bu konuya pek rastlamadık; genelde yalnızca ilk kurulumdaki doğrulama adımı anlatılıyor, imza tarafı atlanıyor.
Kısa Cevap
Meta her POST isteğine X-Hub-Signature-256 başlığı ekler. Bu, isteğin ham gövdesinin uygulama gizli anahtarınızla (app secret) hesaplanmış HMAC-SHA256 değeridir. Aynı hesabı n8n'de yapıp başlıktaki değerle karşılaştırırsınız; tutmuyorsa isteği işlemeden bırakırsınız. En sık hata, hash'i ayrıştırılmış JSON üzerinden hesaplamaya çalışmaktır.
İki Ayrı Doğrulama Var
İkisi sık karıştırılıyor. Birincisi webhook'u ilk kez tanımlarken olur: Meta adresinize bir GET isteği atar, içinde hub.mode=subscribe, hub.verify_token ve hub.challenge bulunur. verify_token sizin seçtiğiniz bir metindir. Gelen değer sakladığınız değerle eşleşiyorsa, hub.challenge değerini 200 koduyla geri döndürürsünüz. Meta'nın dokümantasyonuna göre bunun dışındaki her yanıt, 400'lü kodlar dahil, adresi doğrulanmamış bırakır ve hiçbir webhook gelmez.
İkincisi sürekli çalışan imza kontrolüdür ve asıl güvenliği o sağlar. verify_token yalnızca kurulum anında bir kez sorulur. Sonrasında gelen mesaj olaylarının kaynağını doğrulayan şey imzadır.
İmza Nasıl Oluşuyor?
Meta'nın tarif ettiği biçim şu: X-Hub-Signature-256 başlığının değeri "sha256=" ile başlar, ardından bir hash gelir. Bu hash, isteğin gövdesi ve uygulamanızın gizli anahtarı kullanılarak hesaplanan bir HMAC-SHA256'dır. Sizin yapacağınız şey aynı hesabı gelen gövde ve kendi gizli anahtarınızla yapmak, sonucu başlıktaki "sha256=" sonrasıyla karşılaştırmak. Eşleşiyorsa Meta'nın dokümanındaki ifadeyle yük geçerlidir ve 200 döndürürsünüz; eşleşmiyorsa 200 dışında bir kod döndürürsünüz.
Gizli anahtar, Meta for Developers panelinde uygulamanızın ayarlarında bulunan app secret değeridir. Bunu workflow içine düz metin yazmak yerine n8n'in credential yapısında ya da ortam değişkeninde tutmak daha doğru.
Neden Ham Gövde Şart?
HMAC, gövdenin birebir baytlarına bağlıdır. Tek bir boşluk ya da kaçış karakteri farkı bambaşka bir hash üretir. n8n Webhook düğümü gelen JSON'u otomatik ayrıştırır; ayrıştırılmış nesneyi tekrar metne çevirdiğinizde anahtar sırası, boşluklar ve özel karakterlerin yazımı değişebilir. Meta'nın kullandığı biçimle sizinki aynı çıkmaz ve doğru bir istek bile "geçersiz" görünür. n8n topluluk forumunda da bu yüzden imzaların hiç tutmadığını anlatan bir başlık var: gönderen tarafın ham gövdesinde eğik çizgiler kaçışlıydı, n8n'in gösterdiği gövdede değildi.
Çözüm, hash'i ham baytlar üzerinden almak. n8n'in Webhook düğümünde bunun için Raw Body seçeneği var. Dokümantasyon bu seçeneği, düğümün veriyi JSON ya da XML gibi ham biçimde alması olarak tanımlıyor. Bir topluluk anlatımına göre bu seçenek açıldığında ayrıştırılmış gövdenin yanında istek baytları binary veri olarak da tutuluyor. Bu davranış sürümler arasında değişebileceği için kendi kurulumunuzda bir test isteğiyle kontrol edin.
n8n'de Kurulum
Akışın iskeleti şöyle:
- Webhook düğümü: Raw Body seçeneğini açın. İki ayrı yöntem kullanacaksanız GET (doğrulama) ve POST (olaylar) için ayrı yollar tanımlamak işi sadeleştirir.
- İmza hesabı: Crypto düğümünün Hmac işlemini kullanabilirsiniz. Dokümantasyona göre SHA256 destekleniyor, çıktı HEX ya da BASE64 olabiliyor. Meta hash'i hex olarak gönderdiği için HEX seçin ve girdi olarak ham gövdeyi verin. Code düğümünü tercih ederseniz Node'un crypto modülü gerekir; n8n güvenlik nedeniyle modül kullanımını kısıtlıyor ve NODE_FUNCTION_ALLOW_BUILTIN=crypto ayarını istiyor. Task Runner kullanıyorsanız bu ayar main düğümde değil Task Runner'da yapılmalı.
- Karşılaştırma: Başlıktaki değerden "sha256=" önekini atın, hesaplanan hex ile karşılaştırın. Mümkünse zamanlamaya dayanıklı bir karşılaştırma kullanın; Code düğümünde crypto.timingSafeEqual bunu sağlar.
- If düğümü: Eşleşmeyen istekte akışı durdurun ve Respond to Webhook ile 400'lü bir kod döndürün. Eşleşirse devam edin.
Webhook düğümü varsayılan olarak hemen "Workflow got started" yanıtı verir. İmza sonucuna göre farklı kod döndürmek istiyorsanız yanıt modunu Respond to Webhook düğümüne almanız gerekir.
Meta'ya Ne Zaman 200 Dönmeli?
Meta'nın anlattığına göre başarısız teslimatlar hemen, sonra azalan sıklıkla 7 gün boyunca yeniden denenir. Yani akışınız yavaşsa ya da hata veriyorsa aynı mesaj size defalarca gelebilir. İki önlem işe yarıyor. Birincisi, imzayı doğrulayıp hemen 200 dönmek, uzun işleri sonra yapmak. İkincisi, her mesajın kimliğini bir tabloya yazıp daha önce işlenmiş olanı atlamak. Meta ayrıca isteklerin toplu gelebileceğini, tek istekte en fazla 1000 güncelleme bulunabileceğini ve bunun garanti edilmediğini söylüyor; her isteği ayrı ayrı ve döngüyle işleyin.
Ek Katmanlar
İmza kontrolü yeterli olsa da üstüne eklenebilecek şeyler var. Meta webhook'lar için karşılıklı TLS (mTLS) desteğini de belgeliyor; her uygulama için ayrı etkinleştirilmesi gerekiyor. n8n tarafında Webhook düğümünde bir IP izin listesi seçeneği var, dışarıdan gelen istek 403 alıyor, ama bunun işe yaraması için Meta'nın kullandığı adresleri güncel tutmanız gerekir ve adres listesi değişebilir. Bu yüzden bunu imzanın yerine değil yanına koyun. Uç noktanın geçerli bir TLS sertifikası olmalı; Meta kendinden imzalı sertifikayı desteklemiyor.
Barındırma tercihi de burada rol oynuyor. Kendi sunucunuzda çalışan n8n'de ortam değişkenlerini, ters proxy ayarlarını ve sertifikayı siz yönetirsiniz; bulutta bir kısmı sağlayıcıda kalır. Karşılaştırma için self-hosted ve cloud maliyet yazımıza bakabilirsiniz. Webhook'tan gelen müşteri verisinin nerede saklandığı da ayrı bir konu: KVKK uyumlu otomasyon yazısında anlattık.
Test Etmenin Pratik Yolu
Önce Test URL ile kurun, doğru hash'in hesaplandığını görün, sonra Production URL'ye geçin. n8n dokümantasyonuna göre test webhook'u yalnızca dinleme modundayken kayıtlı, production adresi ise workflow yayınlandığında kayıt oluyor. Meta panelinde Production adresi tanımlıysa test modundaki akış hiçbir şey görmez. Sonra bilerek yanlış bir gizli anahtar kullanıp imzanın reddedildiğini kontrol edin. Reddetme tarafını denemeyen bir doğrulama, çalıştığını kanıtlamış sayılmaz.
Reklamdan gelen mesajların satışa bağlanması gibi daha ileri akışları kurmadan önce bu temelin sağlam olması iyi olur; reklam tarafını ctwa_clid yazısında anlattık.
Sık Sorulanlar
WhatsApp webhook imzasını doğrulamak zorunlu mu?
Meta'nın dokümantasyonu imzayı doğrulamanızı ve geçerliyse 200 dönmenizi anlatıyor. Doğrulamazsanız webhook adresinizi bilen herkes sahte bir mesaj olayı gönderebilir ve akışınız bunu gerçek müşteri mesajı sanır.
İmzayı neden ayrıştırılmış JSON üzerinden hesaplayamıyorum?
HMAC, gövdenin birebir baytları üzerinden hesaplanır. JSON'u ayrıştırıp yeniden yazdığınızda boşluklar, kaçış karakterleri ve alan sırası değişebilir ve hash tutmaz. Bu yüzden ham gövdeyle çalışmak gerekir.
Meta aynı olayı birden fazla kez gönderirse ne olur?
Meta başarısız teslimatları hemen, ardından 7 gün boyunca azalan sıklıkla yeniden dener. Bu yüzden akışınızın aynı mesaj kimliğini ikinci kez işlememesi gerekir.
Kaynaklar: Meta for Developers, "Create a webhook endpoint" · n8n Docs, Webhook node · n8n Docs, Crypto node · n8n Docs, Modules in the Code node · n8n Community, HMAC doğrulama örneği · n8n Community, ham gövde sorunu. Arayüz ve davranışlar sürümlere göre değişebilir; kendi kurulumunuzda test edin.
Webhook akışınızın güvenliğini birlikte gözden geçirelim
WhatsApp akışınızda imza kontrolü, tekrar eden olay ve hata yönetimini yarım saatte kontrol edelim.