Как перенести webhook n8n на новый домен и проверить входящие события

Новый экземпляр n8n может открываться по новому домену, но это ещё не означает, что входящие события пойдут туда. Форма, платёжный сервис или другая внешняя система могут продолжать отправлять запросы на старый webhook URL.

Поэтому перенос нужно планировать как переключение всей цепочки: найти отправителей, подготовить публичный адрес, обновить каждую регистрацию, провести контрольные события и только потом отключать старый маршрут.

Почему смена домена не заканчивается настройкой сервера

У миграции есть две разные задачи:

1. n8n должен формировать и показывать правильный публичный webhook URL.
2. Каждый внешний отправитель должен использовать этот URL.

За обратным прокси внутренний адрес n8n может отличаться от публичного. Например, n8n принимает трафик на внутреннем порту, а пользователи и внешние сервисы обращаются к HTTPS-домену через прокси.

Для конфигурации с обратным прокси документация n8n предписывает вручную задать N8N_WEBHOOK_URL. Эта переменная помогает n8n показывать правильный адрес в редакторе и регистрировать webhook во внешних сервисах. Но она не доказывает, что каждая ранее созданная регистрация уже обновилась.

Механизм зависит от интеграции. Где-то адрес вводит сотрудник в кабинете отправителя. Где-то узел n8n регистрирует webhook через API внешнего сервиса. Иногда изменением управляет другая команда. Поэтому один общий переключатель не заменяет реестр интеграций.

Составьте реестр входящих интеграций до переключения

Начните не с DNS, а со списка всех известных входящих каналов. Для каждого канала зафиксируйте:

Не считайте, что n8n автоматически обнаружит всех отправителей. Реестр собирают по workflow, настройкам внешних систем, документации и сведениям владельцев процесса.

Для автоматически регистрируемого webhook отдельно выясните, когда узел обновляет регистрацию: при публикации workflow, активации, повторном подключении или другом действии. Ответ нужно брать из документации конкретного узла и подтверждать фактически зарегистрированным адресом во внешнем сервисе.

Подготовьте новый публичный адрес за обратным прокси

Для описанной в официальной документации n8n конфигурации за обратным прокси нужны три настройки:

1. Задать публичный адрес в N8N_WEBHOOK_URL.
2. Установить N8N_PROXY_HOPS=1.
3. Передавать на последнем прокси заголовки X-Forwarded-For, X-Forwarded-Host и X-Forwarded-Proto.

Значение N8N_PROXY_HOPS=1 относится к топологии, которую описывает источник. Для иной цепочки прокси не следует переносить его без проверки документации и реального маршрута запроса.

Начиная с n8n 2.35.0, N8N_WEBHOOK_URL заменяет устаревшую переменную WEBHOOK_URL. При подготовке действующего экземпляра сначала уточните его версию и сопоставьте настройки с актуальной документацией.

Эти параметры отвечают за формирование публичных webhook URL и передачу сведений о первоначальном запросе. Они сами по себе не обеспечивают настройку DNS и TLS, проверку подлинности отправителя, защиту от повторной обработки или сохранность событий. Эти свойства нужно отдельно проектировать и проверять для конкретного процесса.

Спланируйте регистрацию нового URL у каждого отправителя

Порядок переключения зависит от строки в реестре.

Адрес указан вручную. Определите, кто откроет кабинет или конфигурацию отправителя, заменит URL и сохранит изменение. До замены зафиксируйте старое значение и условие возврата.

Webhook регистрирует узел n8n. Уточните по документации конкретного узла, какое действие создаёт или обновляет регистрацию. После этого проверьте во внешнем сервисе, что зарегистрирован новый адрес. Изменение N8N_WEBHOOK_URL нельзя считать универсальной гарантией обновления всех существующих регистраций.

Интеграцией управляет другая команда или подрядчик. Передайте им новый URL, время переключения, контрольное событие и способ подтверждения. Назначьте человека, который сверит результат со стороны n8n и целевой системы.

Для каждого варианта заранее запишите:

• исходное состояние;
• действие для обновления;
• ответственного;
• контрольное событие и его идентификатор;
• ожидаемый результат;
• условие возврата на старую конфигурацию.

Условный пример переключения двух интеграций

Ниже синтетический учебный пример, а не клиентский кейс и не отчёт о выполненном тесте.

Компания переносит n8n с https://old.example.test/ на https://new.example.test/. Форма сайта использует обычный Webhook Trigger: адрес вручную записан в настройках формы. Второй внешний сервис работает через узел n8n, который регистрирует webhook через API сервиса.

После отправки возможны три разные ситуации.

Событие прошло полностью. Идентификатор совпал, нужный workflow запустился, входные поля верны, последующие узлы завершили согласованные действия, а результат появился в целевой системе.

Workflow запустился, но дальнейшее действие завершилось ошибкой. Новый URL работает, однако процесс нельзя считать успешно завершённым. Ответственный разбирает ошибку последующего узла и проверяет, не произошло ли частичное или необратимое действие.

Одно событие пришло через оба адреса. Не запускайте обработку повторно вслепую. Сначала сопоставьте идентификатор, оба execution и результаты в целевой системе. Затем решите, требуется ли компенсация, пропуск дубля или другое действие по правилам процесса.

Проверьте полный путь события, а не только HTTP-ответ

Проверка должна пройти семь звеньев:

1. Отправитель сформировал контрольное событие.
2. Он использовал новый зарегистрированный URL.
3. Запрос дошёл до n8n.
4. Webhook Trigger активировал нужный production workflow.
5. Входные поля совпали с контрольным событием.
6. Последующие узлы выполнили ожидаемые действия.
7. Результат появился в целевой системе.

Успешный HTTP-ответ подтверждает только часть пути. Он не доказывает, что дальнейшие узлы завершили работу и бизнес-результат появился там, где его ждут.

По документации n8n каждый входящий запрос, который активировал Webhook Trigger, считается отдельным execution. Запрос, отклонённый или признанный некорректным до запуска workflow, execution не создаёт. Поэтому отсутствие execution и execution с ошибкой требуют разных проверок.

Наличие execution подтверждает запуск workflow, но не успешное завершение процесса. Сопоставляйте идентификатор события, входные данные, состояние узлов и результат в целевой системе.

Проверьте наблюдаемость до миграции

До переключения откройте настройки каждого затронутого workflow и выясните, сохраняет ли n8n:

• неуспешные production executions;
• успешные production executions.

n8n предоставляет для них отдельные настройки. Если сохранение успешных выполнений отключено, отсутствие записи в доступном списке само по себе не доказывает, что событие не дошло.

Также зафиксируйте, какие данные видит ответственный. В экземпляре может быть включено скрытие данных production execution, а доступ сотрудника может быть ограничен. Срок хранения, состав инфраструктурных журналов и права нужно определять отдельно: настройки workflow не обещают полную историю по умолчанию.

До миграции запишите доступные точки наблюдения: журнал отправителя, регистрацию webhook во внешнем сервисе, список executions, доступные журналы прокси и результат в целевой системе. Тогда при отклонении команда сможет проверять цепочку по частям.

Что делать с пропущенными и повторными событиями

Для будущего внедрения заранее определите устойчивый идентификатор события, источник истины, допустимость повторной обработки и человека, который принимает решение.

Если событие предположительно пропущено:

1. Проверьте, сохраняются ли успешные production executions.
2. Найдите событие в журнале отправителя и уточните использованный URL.
3. Проверьте фактическую регистрацию webhook.
4. Сверьте доступные журналы маршрутизации и прокси.
5. Найдите execution по идентификатору, если данные сохраняются.
6. Проверьте целевую систему: действие могло завершиться, даже если доступная история неполна.

Если событие повторилось, сначала выясните результат первой обработки. Особое внимание нужно необратимым действиям: отправке сообщения, списанию, созданию записи или изменению статуса. Только после этого можно решать, запускать ли событие снова.

Подробнее порядок восстановления разобран в материале о сбоях workflow, а проектирование защиты — в руководстве о предотвращении повторной обработки.

Идемпотентность, очередь повторной доставки и автоматическое восстановление — не свойства любого workflow по умолчанию. Их проектируют и проверяют для конкретного процесса.

Когда можно отключить старый адрес

Старый маршрут можно выводить из эксплуатации, когда выполнены критерии конкретной миграции:

• все известные интеграции из реестра обновлены подходящим способом;
• автоматические регистрации проверены во внешних сервисах;
• отправители с ручной настройкой используют новый URL;
• для значимых типов событий подтверждён полный путь до целевого результата;
• настройки сохранения executions учтены при диагностике;
• найденные пропуски и повторы разобраны;
• для поздних событий определены ответственный и порядок обработки;
• условие возврата больше не требуется либо заменено согласованным планом восстановления.

Универсального срока параллельной работы старого и нового адресов нет. Два доступных маршрута могут помочь при переключении, но также создают риск дублей, если отправитель направит одно событие на оба URL.

Такой реестр не гарантирует обнаружение неизвестных интеграций. Статья также не заменяет документацию внешнего сервиса и не доказывает, что конкретный workflow защищён от повторной обработки.

Если нужно перенести действующие webhook и согласовать переключение между несколькими владельцами систем, Switch On AI помогает с разработкой и внедрением автоматизации: разбирает зависимости, формирует требования, проектирует порядок миграции и критерии приёмки. Для первого обсуждения подготовьте список workflow, отправителей, старых адресов, способов регистрации и ожидаемых результатов событий, затем опишите задачу на странице контактов.