Автентифікація вебхуків n8n: Header, Basic чи JWT
Автентифікація вебхуків n8n крок за кроком: додайте Header, Basic чи JWT до вузла Webhook, перевірте виклики через curl і оберіть метод.
Перевірено за наведеними джерелами .
Мета та передумови
Цей туторіал показує автентифікацію вебхуків n8n на навчальному робочому процесі. Мета — вузол Webhook, який відхиляє виклики без дійсних облікових даних і приймає ті, що їх мають. Згідно з документацією n8n, вузол Webhook може вимагати від викликальників автентифікації через Basic auth, Header auth або JWT auth, або ж не вимагати жодної.
Вам потрібні робочий простір n8n, workflow із тригером Webhook і curl або Postman для надсилання запитів. Цей посібник підготовлено на основі наданої документації та джерел спільноти. Ми не тестували його самостійно, тож перевіряйте кожен результат на своїй версії n8n.
Sources: Webhook | Nodes | n8n Docs
Кроки: додаємо автентифікацію вебхука n8n з обліковими даними Header auth
Для навчальної збірки ми використовуємо Header auth, бо вона потребує найменше налаштувань. Кроки нижче впорядковані; виконуйте їх послідовно. Послідовність тестів і довге випадкове значення — це наша рекомендована практика, а не документована процедура n8n.
- Додайте вузол Webhook і запишіть і тестову, і робочу URL-адреси.
- Створіть облікові дані Header auth: введіть Name і Value заголовка. Використайте довге випадкове значення.
- У вузлі Webhook встановіть Authentication на Header auth і виберіть ці облікові дані.
- Викличте тестову URL-адресу через curl: один раз без заголовка, один раз із хибним значенням і один раз із правильним.
- Опублікуйте workflow, потім повторіть три виклики до робочої URL-адреси та перевірте вкладку Executions.
Вузол Webhook має окремі тестову та робочу (production) URL-адреси. Тестова реєструється, коли ви використовуєте Listen for Test Event або запускаєте workflow, поки він неактивний, і тоді редактор показує вхідні дані. Робоча реєструється, коли ви публікуєте workflow, а її виклики відображаються на вкладці Executions, а не в редакторі. У старіших версіях n8n замість «опублікувати» може бути «активувати».
На нашу думку, довге випадкове значення заголовка — правильний вибір для першої збірки. Його просто створити, просто надіслати з curl і просто змінити пізніше. Як редакційне очікування, а не документована поведінка: виклик без заголовка або з хибним значенням має бути відхилений і не запускати workflow. Правильне значення має його запустити, що видно в редакторі для тестової URL-адреси або в Executions для робочої.
Sources: Webhook | Nodes | n8n Docs, Webhook credentials | Nodes | n8n Docs
Basic auth або автентифікація вебхуків n8n через JWT
Basic auth використовує облікові дані з Username і Password. Документація n8n каже, що JWT auth використовує облікові дані JWT, тип ключа яких — Passphrase або PEM key. Документація з облікових даних перелічує варіанти passphrase (секрет HMAC) або пару ключів PEM, а також алгоритми сімейств HS, RS, ES і PS плюс none. Документація не дає порад щодо безпеки опції none, тож дослідіть її, перш ніж обирати.
- Створіть облікові дані: Username і Password для Basic auth або облікові дані JWT із Passphrase чи PEM key і алгоритмом.
- У вузлі Webhook встановіть Authentication на Basic auth або JWT auth.
- Виберіть створені облікові дані в полі credential вузла.
- Для JWT надішліть токен у заголовку Authorization із префіксом Bearer, як описують учасники спільноти.
- Виконайте ті самі тестові виклики, що й у кроках Header auth.
Учасник спільноти написав у квітні 2025 року, що JWT надсилається в заголовку Authorization із префіксом Bearer, а тригер Webhook тоді надає вміст токена у властивості jwtPayload. Це розповідь спільноти, а не документована поведінка. Туторіал на Medium від вересня 2025 року розглядає токен Auth0: облікові дані з ключем PEM, що містить публічний ключ, і алгоритм на кшталт RS256.
Будьте обережні з claims. Засновник консалтингової компанії, пишучи в блозі вендора у вересні 2025 року, наводить таке застереження. Наявна в нас документація не вказує, які claims охоплює вбудована перевірка, тож протестуйте з простроченим токеном.
Basic auth має власне застереження щодо версій. У GitHub issue щодо n8n 2.9.0 повідомлялося про 403 замість 401 для хибних облікових даних Basic auth, а згодом мейнтейнер сказав, що це виправлено в n8n 2.30.0. Коди статусу відхилених викликів можуть залежати від версії.
Sources: Webhook credentials | Nodes | n8n Docs, JWT credentials | Nodes | n8n Docs, Using JWTs (JSON Web Tokens) for Authenticated Webhooks - Tips & Tricks - n8n Community, Authentication with n8n is Easier Than You Think | by Sean Spaniel | Medium, n8n Webhooks: A Beginner’s Guide (with Security Built-In), Webhook Basic Auth Returns 403 Instead of 401 for Invalid Credentials · Issue #26365 · n8n-io/n8n · GitHub
Вибір методу для робочих викликальників
Надана документація не дає рейтингу безпеки трьох методів автентифікації вебхуків n8n. Порівняння нижче — редакційна порада, що почасти повторює блог вендора n8nlogic за 2026 рік, який радить Header auth для викликів машина–машина та JWT, коли викликальник уже видає токени, а Basic auth вважає найслабшою. Цей блог просуває власні послуги, тож сприймайте його як думку.
| Метод | Поля облікових даних | Рекомендоване застосування |
|---|---|---|
| Header auth | Name і Value заголовка | Типовий вибір для викликальників «система–система» |
| JWT | Passphrase або PEM key | Викликальники, що вже видають підписані токени |
| Basic auth | Username і Password | Лише коли викликальник не пропонує нічого іншого |
Ми б уникали Basic auth, якщо викликальник не підтримує нічого іншого.
Sources: Webhook credentials | Nodes | n8n Docs, n8n Webhook Node: Triggers, Auth & Responding (2026) | n8nlogic
Посилення захисту, ротація секретів і усунення проблем
Окрім автентифікації вебхуків n8n, опція IP(s) Allowlist вузла Webhook повертає 403 для викликальників поза списком, а порожній список дозволяє всі адреси. Вона обмежує коло тих, хто може спробувати, тож використовуйте її на додачу до автентифікації, а не замість неї.
Одна вендорська агенція радить окремі облікові дані для кожної системи-викликальника, щоб ротація одного секрету не ламала решту. Вона також попереджає, що залишена автентифікація none дозволяє будь-кому з URL запустити workflow. Автор зі спільноти додає, що дуже довгі терміни дії токенів ускладнюють анулювання викраденого токена. Щодо зберігання, n8n документує зовнішні сховища секретів в n8n Cloud Enterprise та self-hosted Enterprise з провайдерами на кшталт HashiCorp Vault і AWS Secrets Manager; сторінка не каже, чи можуть облікові дані вебхуків їх використовувати.
Якщо виклик не відхиляється, перевірте, що Authentication вузла не залишилася none і що ви викликали URL правильного режиму. Якщо всі виклики падають, точно порівняйте Name і Value заголовка. Не діліться URL-адресою, доки відхилені виклики не почнуть падати очікувано.
Sources: Webhook | Nodes | n8n Docs, Using JWTs (JSON Web Tokens) for Authenticated Webhooks - Tips & Tricks - n8n Community, Configure the n8n Webhook Node: 15 Parameters Explained | Hack'celeration, Use external secret stores | Administer | n8n Docs
