n8n은 여러 서비스를 노드로 이어 붙여 업무를 자동화하는 오픈소스 도구입니다. 웹훅으로 요청을 받아 처리하고 응답하는 가장 단순한 형태를 만들어, 실제로 호출되는 것까지 확인합니다. 화면에서 노드를 끌어다 놓는 대신 워크플로를 JSON 파일로 가져오는 방식을 썼습니다.
준비물
| 항목 | 확인한 값 |
|---|---|
| Docker | 29.5.3 (Windows 11) |
| n8n | 2.45.5 (n8nio/n8n:2.45.5, 처음에 latest로 받았을 때도 같은 버전) |
1. 실행
docker run -d --name osk-n8n -p 127.0.0.1:3903:5678 \
-v osk_n8n:/home/node/.n8n -v "<워크플로 폴더>:/wf" \
-e N8N_SECURE_COOKIE=false n8nio/n8n:2.45.5
127.0.0.1:3903: 이 PC에서만 접속됩니다.N8N_SECURE_COOKIE=false: HTTPS 없이 localhost에서 쓰기 위한 실습용 설정입니다. 실제 운영에서는 끄지 않습니다.
약 30초 뒤 /healthz가 HTTP 200을 돌려주었습니다. 다만 200이 나왔다고 바로 명령을 보내면 안 됩니다. 두 번째로 실행했을 때 healthz가 200이 된 직후 docker exec가 "container is not running" 오류를 냈고, 컨테이너를 다시 만들어 실행하자 정상이었습니다. 첫 실행 때 내부 준비로 컨테이너가 잠시 다시 시작되는 것으로 추정합니다. 그 뒤 스크립트에는 healthz 뒤에 20초를 더 기다리고 컨테이너 상태를 확인하는 줄을 넣었습니다.
2. 워크플로
노드 두 개를 이은 워크플로 hello-webhook을 JSON 파일로 만들었습니다.
- Webhook 노드:
POST /hello를 받고 마지막 노드의 결과를 응답으로 돌려줍니다(responseMode: lastNode). - Code 노드: 요청 본문의
name으로{greeting, length}를 만듭니다.name이 없으면unknown을 씁니다.

docker exec osk-n8n n8n import:workflow --input=/wf/wf.json
docker exec osk-n8n n8n list:workflow
# 기대 출력
Successfully imported 1 workflow.
wfhello0000000001|hello-webhook
3. 게시와 재시작
docker exec osk-n8n n8n publish:workflow --id=wfhello0000000001
게시 명령은 "n8n이 실행 중이면 변경이 적용되지 않으니 재시작하라"고 안내했고, 같은 명령 뒤에 n8n execute를 실행했더니 포트 5679가 이미 쓰이고 있다는 오류가 났습니다(실행 중인 서버와 충돌). 안내대로 컨테이너를 재시작했습니다.
docker restart osk-n8n
4. 호출 결과
requests.post("http://127.0.0.1:3903/webhook/hello", json={"name": "민수"})
| 요청 | 응답 |
|---|---|
POST /webhook/hello {"name": "minsu"} |
200 {"greeting":"hello minsu","length":5} |
POST {"name": "민수"} |
200 {"greeting":"hello 민수","length":2} |
POST {} |
200 {"greeting":"hello unknown","length":7} |
GET /webhook/hello |
404 This webhook is not registered for GET requests |
POST /webhook-test/hello |
404 The requested webhook "hello" is not registered |
- 한글 이름도 처리됐고
length는 글자 수 2였습니다. - 빈 본문에는 코드의 기본값
unknown이 쓰였습니다. GET이 막힌 것은 웹훅 노드를POST로 설정한 결과입니다.
curl로 POST를 보내면 greeting과 length가 든 JSON이 돌아오고, 같은 주소를 GET으로 부르면 POST로 요청하라는 404 메시지가 나오는 것을 확인합니다.
Executions 탭에는 호출한 만큼 실행 기록이 쌓였습니다.

/webhook-test/주소는 화면에서 "Execute workflow"를 누른 직후 한 번만 동작하는 시험용이라, 게시한 워크플로는/webhook/로 호출합니다.
5. 두 번째 워크플로: 헤더를 확인하고 상태 코드 고르기
첫 워크플로는 누가 불러도 200을 돌려줍니다. 요청 헤더 x-token이 약속한 값일 때만 200을, 아니면 401을 돌려주는 guarded-webhook을 만들었습니다. 노드는 네 개입니다.
- Webhook:
POST /guarded를 받습니다. 이번에는responseMode가responseNode라서, 응답을 마지막 노드가 아니라 응답 노드가 정합니다. - IF(Check token):
$json.headers['x-token']이lab-secret과 같은지 검사합니다. 같으면 위쪽(true), 다르거나 헤더가 없으면 아래쪽(false) 출력으로 갑니다. - Respond 200:
{ok: true, echo: <본문의 text>}를 상태 코드 200으로 돌려줍니다. - Respond 401:
{ok: false, error: 'bad token'}을 상태 코드 401로 돌려줍니다.
| 요청 | 응답 |
|---|---|
x-token: lab-secret, 본문 {"text":"hi"} |
200 {"ok":true,"echo":"hi"} |
x-token: wrong |
401 {"ok":false,"error":"bad token"} |
| 헤더 없음 | 401 {"ok":false,"error":"bad token"} |
헤더가 없는 경우도 같은 401이 나왔습니다. 값이 비어 있으면 lab-secret과 같지 않아서 false 쪽으로 가기 때문입니다.
이 방식은 연습용입니다. 비밀 값이 워크플로 JSON 안에 평문으로 들어 있어서 파일을 공유하면 같이 새어 나갑니다. 값을 비교하는 방식이어서 요청마다 값이 바뀌는 인증이 아닙니다. 실제로 쓸 때는 Webhook 노드 자체의 인증 설정(Header Auth 등)에 n8n의 자격 증명 저장소를 연결합니다. 이 글에서는 자격 증명 방식을 시험하지 않았습니다.
파이썬에서 부르려면 이렇게 합니다.
import requests
r = requests.post("http://127.0.0.1:3903/webhook/guarded",
headers={"x-token": "lab-secret"}, json={"text": "hi"})
print(r.status_code, r.json()) # 200 {'ok': True, 'echo': 'hi'}
6. 운영 전에 정할 것
| 항목 | 내용 |
|---|---|
| 인증 | 웹훅 주소를 아는 누구나 호출 가능. 운영에서는 인증 헤더 등을 설정. 이 글에서는 인증 없이 확인 |
| 외부 노출 | 인터넷에 열 때는 HTTPS와 접근 제한이 우선 |
| 데이터 저장 | 워크플로와 실행 기록이 볼륨 osk_n8n에 남음 |
전체 코드
아래 JSON이 이 글에서 가져온 워크플로 전체입니다. wf.json으로 저장하고 컨테이너에 연결한 폴더에 둔 뒤 위 2번의 import:workflow 명령으로 가져옵니다. Webhook 노드의 path가 호출 주소(/webhook/hello)를 정합니다.
wf.json
{
"id": "wfhello0000000001",
"name": "hello-webhook",
"active": false,
"nodes": [
{
"parameters": {
"httpMethod": "POST",
"path": "hello",
"responseMode": "lastNode",
"options": {}
},
"id": "11111111-1111-4111-8111-111111111111",
"name": "Webhook",
"type": "n8n-nodes-base.webhook",
"typeVersion": 2,
"position": [0, 0],
"webhookId": "22222222-2222-4222-8222-222222222222"
},
{
"parameters": {
"jsCode": "const name = $input.first().json.body.name || 'unknown';\nreturn [{ json: { greeting: 'hello ' + name, length: name.length } }];"
},
"id": "33333333-3333-4333-8333-333333333333",
"name": "Code",
"type": "n8n-nodes-base.code",
"typeVersion": 2,
"position": [220, 0]
}
],
"connections": {
"Webhook": { "main": [[{ "node": "Code", "type": "main", "index": 0 }]] }
},
"settings": {}
}
두 번째 워크플로 wf2.json
IF 노드의 conditions 구조는 n8n 2.x 형식입니다. 버전이 다르면 구조가 달라서 가져오기는 되어도 노드 안이 비어 보일 수 있습니다.
wf2.json
{
"id": "wfguard0000000002",
"name": "guarded-webhook",
"active": false,
"nodes": [
{
"parameters": { "httpMethod": "POST", "path": "guarded", "responseMode": "responseNode", "options": {} },
"id": "44444444-4444-4444-8444-444444444444",
"name": "Webhook",
"type": "n8n-nodes-base.webhook",
"typeVersion": 2,
"position": [0, 0],
"webhookId": "55555555-5555-4555-8555-555555555555"
},
{
"parameters": {
"conditions": {
"options": { "caseSensitive": true, "leftValue": "", "typeValidation": "strict", "version": 2 },
"conditions": [
{
"id": "66666666-6666-4666-8666-666666666666",
"leftValue": "={{ $json.headers['x-token'] }}",
"rightValue": "lab-secret",
"operator": { "type": "string", "operation": "equals" }
}
],
"combinator": "and"
},
"options": {}
},
"id": "77777777-7777-4777-8777-777777777777",
"name": "Check token",
"type": "n8n-nodes-base.if",
"typeVersion": 2.2,
"position": [220, 0]
},
{
"parameters": {
"respondWith": "json",
"responseBody": "={{ { ok: true, echo: $('Webhook').item.json.body.text || '' } }}",
"options": { "responseCode": 200 }
},
"id": "88888888-8888-4888-8888-888888888888",
"name": "Respond 200",
"type": "n8n-nodes-base.respondToWebhook",
"typeVersion": 1.1,
"position": [460, -80]
},
{
"parameters": {
"respondWith": "json",
"responseBody": "={{ { ok: false, error: 'bad token' } }}",
"options": { "responseCode": 401 }
},
"id": "99999999-9999-4999-8999-999999999999",
"name": "Respond 401",
"type": "n8n-nodes-base.respondToWebhook",
"typeVersion": 1.1,
"position": [460, 100]
}
],
"connections": {
"Webhook": { "main": [[{ "node": "Check token", "type": "main", "index": 0 }]] },
"Check token": { "main": [
[{ "node": "Respond 200", "type": "main", "index": 0 }],
[{ "node": "Respond 401", "type": "main", "index": 0 }]
] }
},
"settings": {}
}
전체를 한 번에: run_n8n.sh
컨테이너 실행부터 가져오기, 게시, 재시작, 두 워크플로 호출, 컨테이너와 볼륨 삭제까지 한 번에 하는 파일입니다. wf.json, wf2.json과 같은 폴더에 run_n8n.sh로 저장하고 bash run_n8n.sh로 실행합니다. 이 PC에서는 약 2분 걸렸습니다. 끝에서 컨테이너와 osk_n8n 볼륨만 지웁니다.

#!/usr/bin/env bash
# n8n 컨테이너를 띄워 워크플로 두 개를 가져와 게시하고, 호출 결과를 확인한 뒤 모두 지운다.
# 준비: Docker, 이 폴더의 wf.json 과 wf2.json, curl
# 실행(Git Bash): bash run_n8n.sh (약 2분)
set -u
export MSYS_NO_PATHCONV=1 # Git Bash 가 /wf 같은 경로를 바꾸지 않게 한다
HERE="$(pwd -W 2>/dev/null || pwd)" # 윈도우는 C:/... 경로, 리눅스는 그대로
NAME=osk-n8n; PORT=3903; URL=http://127.0.0.1:$PORT
call() { curl -s -w ' [HTTP %{http_code}]\n' "$@"; }
echo "## 1. 실행"
docker run -d --name $NAME -p 127.0.0.1:$PORT:5678 -v osk_n8n:/home/node/.n8n -v "$HERE:/wf" \
-e N8N_SECURE_COOKIE=false n8nio/n8n:2.45.5 >/dev/null
for i in $(seq 1 60); do
[ "$(curl -s -o /dev/null -w '%{http_code}' $URL/healthz)" = "200" ] && { echo "/healthz 200 (${i}번째 확인)"; break; }
sleep 2
done
sleep 20 # 첫 실행 직후에는 내부 준비가 끝날 때까지 기다린다
echo "버전 $(docker exec $NAME n8n --version 2>/dev/null | tail -1), 컨테이너 상태: $(docker inspect -f '{{.State.Status}}' $NAME)"
echo "## 2. 가져오기와 게시"
docker exec $NAME n8n import:workflow --input=/wf/wf.json 2>&1 | tail -1
docker exec $NAME n8n import:workflow --input=/wf/wf2.json 2>&1 | tail -1
docker exec $NAME n8n list:workflow 2>/dev/null
docker exec $NAME n8n publish:workflow --id=wfhello0000000001 2>&1 | tail -1
docker exec $NAME n8n publish:workflow --id=wfguard0000000002 2>&1 | tail -1
docker restart $NAME >/dev/null
for i in $(seq 1 60); do
[ "$(curl -s -o /dev/null -w '%{http_code}' $URL/healthz)" = "200" ] && break
sleep 2
done
sleep 5
echo "## 3. hello-webhook 호출"
call -X POST -H 'content-type: application/json' -d '{"name":"minsu"}' $URL/webhook/hello
call -X POST -H 'content-type: application/json' -d '{}' $URL/webhook/hello
call $URL/webhook/hello
echo "## 4. guarded-webhook 호출(헤더 x-token 검사)"
call -X POST -H 'content-type: application/json' -H 'x-token: lab-secret' -d '{"text":"hi"}' $URL/webhook/guarded
call -X POST -H 'content-type: application/json' -H 'x-token: wrong' -d '{"text":"hi"}' $URL/webhook/guarded
call -X POST -H 'content-type: application/json' -d '{"text":"hi"}' $URL/webhook/guarded
echo "## 5. 정리"
docker rm -f $NAME >/dev/null && docker volume rm osk_n8n >/dev/null && echo "컨테이너와 볼륨 삭제"
docker ps -a --filter name=$NAME --format '{{.Names}}' | wc -l | sed 's/^/남은 컨테이너 /'
자주 막히는 곳
| 증상 | 원인과 해결 |
|---|---|
| 게시했는데 404 | 서버를 재시작했는지 확인. 게시 명령이 "재시작하라"고 안내함 |
첫 실행 직후 docker exec가 "is not running" 오류를 냄 |
healthz가 200이어도 컨테이너가 잠시 다시 시작될 수 있음. 20초쯤 기다린 뒤 docker ps로 상태 확인 |
| 401이 나와야 하는데 200이 나옴 | IF 노드의 값과 헤더 이름 확인. 헤더 이름은 소문자로 읽힘 |
Task Broker's port 5679 is already in use |
실행 중인 서버와 같은 컨테이너에서 CLI로 서버 기능을 또 띄워서 생기는 충돌 |
이미지 태그 latest가 바뀜 |
버전을 고정해 사용 |
확인 범위
- 해 본 것: 2026-10-29, Windows 11 · Docker 29.5.3 · n8n 2.45.5에서 가져오기, 게시, 재시작, 표의 호출을 한 번씩 실행했습니다. 같은 날
run_n8n.sh로 두 워크플로(hello-webhook, guarded-webhook)를 처음부터 끝까지 두 번 실행했고, 매번 끝난 뒤 컨테이너와 볼륨을 삭제했습니다. - 해 보지 않은 것: 웹 화면에서 노드 편집, 외부 서비스 연동, 인증 설정, 게시 전의 호출 결과, 업그레이드. 화면 캡처는 같은 구성을 다시 띄워 관리자 계정을 만든 뒤 찍었고, 첫 접속 때 나오는 설문 창은 닫고 캡처했습니다.
- 읽을 때 주의: 워크플로 파일은 직접 만든 최소 예시입니다.
이 글의 다음 단계
- Open WebUI Ollama 연결: host.docker.internal:11434 고치기Docker로 Open WebUI를 띄워 호스트의 Ollama에 연결하고, 주소를 localhost로 잘못 넣어 모델 목록이 비는 상태를 만든 뒤 원인을 찾아 고칩니다. 환경 변수를 바로잡아도 저장된 설정이 우선해 되돌아오지 않는 동작도 직접 확인합니다.
- Hermes Agent를 호스트가 아닌 Docker 컨테이너에 설치하고 첫 실행하기명령을 직접 실행하는 오픈소스 에이전트 Hermes Agent를 Ubuntu 컨테이너 안에 설치 스크립트로 설치하고, 첫 실행 화면, hermes doctor 점검, ~/.hermes 데이터 폴더 구조, 웹 대시보드 로그인까지 직접 확인합니다.
이 내용을 팀 교육으로 진행하고 싶으신가요?
인원, 수준, 일정에 맞춰 실습 환경까지 준비해 진행합니다. 대상과 기간을 알려 주시면 구성을 제안해 드립니다.
교육 문의하기메일로 보내실 수도 있습니다: fankh111@gmail.com