n8n에서 Webhook 사용하기, Docker + Ngrok

https://cord-ai.tistory.com/191

n8n에서 웹훅(Webhook)이 필요한 이유는 뭘까?

 

이번 글에서는 n8n에서 Webhook 노드를 설정하는 방법에 대해서 알아보겠습니다.

Webhook ?

Webhook은 외부 서비스에서 특정 이벤트가 발생했을 때, 내 서버에 실시간으로 알림을 보내주는 방식입니다.
n8n에서는 Webhook 노드를 통해 외부 요청을 받아 트리거 역할을 수행하고, 다양한 자동화 작업을 이어갈 수 있습니다.
예를 들어:

• 폼 제출 시 Google Sheets에 저장
• 결제 완료 시 이메일 자동 발송
• Gmail 새 메일 수신 시 Slack 알림 전송

등 다양한 시나리오의 시작점이 됩니다.
 

처음 Local에서 진행해보신분이면 확인해보셨을텐데, Webhook 노드를 만들고 Parameter 탭에 있는 URL이 로컬 호스트로 생성이됩니다.
내컴퓨터의 내부 주소이기 때문에 외부에서 이 url로 데이터를 전송할수없습니다. 외부에서 접근 가능한 URL이 필요합니다.(= Ngrok)

 

Docker + Ngrok으로 로컬에서 n8n Webhook 서버 구축하기

n8n은 다양한 서비스와의 연동을 통해 자동화를 구성할 수 있는 강력한 오픈소스 툴입니다. 특히 Telegram, Google Sheets, 이메일, AI 챗봇 등과 연계한 워크플로우를 구성할 수 있어 생산성을 극대화할 수 있죠.
이 글에서는 Docker와 Ngrok을 활용해 외부에서도 접근 가능한 n8n Webhook 서버를 로컬 환경에서 구축한 과정을 정리합니다.

☁️ 준비물

• Docker Desktop 설치 (https://www.docker.com)
  • n8n Docker 이미지
• Ngrok 계정 + 실행파일 (https://ngrok.com)

✅ STEP 1. Docker로 n8n 컨테이너 실행

1. Docker에서 Search에 n8n을 적고, 가장 먼저 뜨는 Image Pull 클릭
2. Images Tab에 n8nio/n8n 재생 버튼 클릭
3. Optional Setting에서 환경변수를 설정해줘야함( > Ngrok)

✅ STEP 2. Docker 실행 시 Optional Setting 추가

Docker Desktop에서 n8n 이미지를 실행하면 Optional Settings을 설정할 수 있는 UI가 나옵니다.

Volumes : 사용할 개인폴더 경로
Container Path : /home/node/ .n8n
Environment variables : 환경 변수

여기서 중요한 환경 변수(Environment Variables)를 추가해야 합니다:

EDITOR_BASE_URL= <Ngrok URL>
WEBHOOK_URL= <Ngrok URL>
N8N_DEFAULT_BINARY_DATA_MODE=filesystem
N8N_COMMUNITY_PACKAGES_ALLOW_TOOL_USAGE=true
N8N_RUNNERS_ENABLED=true

EDITOR_BASE_URL	외부에서 n8n 편집화면 접속용 URL
WEBHOOK_URL	외부 서비스에서 호출할 Webhook URL
DEFAULT_BINARY_DATA_MODE	filesystem으로 설정 시 큰 파일 처리 안정

<영상 참조>

https://www.youtube.com/watch?v=HxJAgWIKTDE

<Ngrok>

• ngrok은 로컬 주소를 외부에서 접속 가능한 HTTPS 주소로 바꿔줌
• 무료 계정으로도 사용 가능
• 기본 도메인은 실행할 때마다 바뀌지만, 고정 주소(Static domain) 설정도 가능

로컬에서 실행 중인 포트를 외부에 터널링해주는 중계 프로그램

❓ 왜 Domain 주소를 넣어야 할까?

로컬에서 n8n을 실행하면 기본 접근 경로는 http://localhost:5678입니다.
하지만 Webhook은 외부 서비스가 우리 서버에 HTTP 요청을 보내야 하는 구조이기 때문에, localhost는 외부에서 접근할 수 없습니다.

• ❌ Telegram, Stripe 등은 localhost 주소를 인식하지 못함
• ✅ 외부에서 접근 가능한 URL (ex: https://xxx.ngrok-free.app)이 반드시 필요

✅ Step 3. Ngrok으로 고정 도메인 발급 및 Docker와 연결

Ngrok 회원가입 후 Ngrok.exe 실행(터미널창이 뜸)

<순서대로 진행>
아래 명령어는 Ngrok 사이트에서 확인가능
1. ngrok config add-authtoken <your-token>
2. ngrok http --url=<your-url> (80)

2번째의 80은 지우고 n8n port 번호를 작성 - 보통 5678로 설정되어있음(본인마음대로)

생성된 URL, 복사후 브라우져에서 확인

이 주소를 Docker 환경 변수에 지정

EDITOR_BASE_URL= Ngrok URL
WEBHOOK_URL= Ngrok URL

<해당 터미널을 종료하면 도메인 연결이 끊김, 종료하지말아주세요.>

- 종료해도 PC가 켜져있으면 상시 가동되는 방법 : Node.js > npm > pm2 적용
https://cord-ai.tistory.com/195

💡 Node.js와 PM2로 ngrok을 상시 실행하는 방법

https://www.youtube.com/watch?v=jQPjPpE_DzI&t=1512s

 

✅ 마무리

이렇게 설정을 마치면, n8n 워크플로우에서 Webhook 노드를 추가하고 POST 요청을 외부에서 보내도 바로 작동합니다.