# n8n으로 웹훅 자동화 만들기: 도커 실행, 워크플로 가져오기, 호출 확인

> 오픈소스 자동화 도구 n8n을 도커로 localhost에만 열어 띄우고, 웹훅을 받아 JSON을 돌려주는 워크플로를 명령줄로 가져와 게시합니다. 게시 전후의 차이, 재시작이 필요했던 점, 한글과 빈 입력과 GET 요청 결과를 확인합니다.

- 주소: https://copyandrun.com/blog/n8n-docker-webhook-workflow/
- 분야: AX
- 발행일: 2026-10-29
- 태그: n8n, 자동화, 웹훅, Docker

n8n은 여러 서비스를 노드로 이어 붙여 업무를 자동화하는 오픈소스 도구입니다. 웹훅으로 요청을 받아 처리하고 응답하는 가장 단순한 형태를 만들어, 실제로 호출되는 것까지 확인합니다. 화면에서 노드를 끌어다 놓는 대신 워크플로를 JSON 파일로 가져오는 방식을 썼습니다.

## 준비물

| 항목 | 확인한 값 |
|---|---|
| Docker | 29.5.3 (Windows 11) |
| n8n | 2.45.5 (`n8nio/n8n:2.45.5`, 처음에 `latest`로 받았을 때도 같은 버전) |

## 1. 실행

<!-- files: run_n8n.sh -->

```bash
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 파일로 만들었습니다.

1. **Webhook 노드:** `POST /hello`를 받고 마지막 노드의 결과를 응답으로 돌려줍니다(`responseMode: lastNode`).
2. **Code 노드:** 요청 본문의 `name`으로 `{greeting, length}`를 만듭니다. `name`이 없으면 `unknown`을 씁니다.

![n8n 편집기 화면에서 hello-webhook 워크플로의 Webhook 노드가 POST 연결선으로 Code 노드에 이어지고 오른쪽 위에 Published 표시가 있는 것을 확인합니다.](https://copyandrun.com/img/n8n-docker-webhook-workflow/01-워크플로-캔버스.png)

```bash
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. 게시와 재시작

```bash
docker exec osk-n8n n8n publish:workflow --id=wfhello0000000001
```

게시 명령은 "n8n이 실행 중이면 변경이 적용되지 않으니 재시작하라"고 안내했고, 같은 명령 뒤에 `n8n execute`를 실행했더니 포트 5679가 이미 쓰이고 있다는 오류가 났습니다(실행 중인 서버와 충돌). 안내대로 컨테이너를 재시작했습니다.

```bash
docker restart osk-n8n
```

## 4. 호출 결과

```python
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 메시지가 나오는 것을 확인합니다.](https://copyandrun.com/img/n8n-docker-webhook-workflow/04-웹훅-호출.png)

Executions 탭에는 호출한 만큼 실행 기록이 쌓였습니다.

![Executions 탭의 목록에 호출 시각별 Succeeded 기록이 5건 있고, 선택한 실행에서 Webhook과 Code 노드가 초록 체크로 표시되며 연결선에 1 item이 적힌 것을 확인합니다.](https://copyandrun.com/img/n8n-docker-webhook-workflow/02-실행-기록.png)

- `/webhook-test/` 주소는 화면에서 "Execute workflow"를 누른 직후 한 번만 동작하는 시험용이라, 게시한 워크플로는 `/webhook/`로 호출합니다.

## 5. 두 번째 워크플로: 헤더를 확인하고 상태 코드 고르기

<!-- files: wf2.json -->

첫 워크플로는 누가 불러도 200을 돌려줍니다. 요청 헤더 `x-token`이 약속한 값일 때만 200을, 아니면 401을 돌려주는 `guarded-webhook`을 만들었습니다. 노드는 네 개입니다.

1. **Webhook:** `POST /guarded`를 받습니다. 이번에는 `responseMode`가 `responseNode`라서, 응답을 마지막 노드가 아니라 응답 노드가 정합니다.
2. **IF(Check token):** `$json.headers['x-token']`이 `lab-secret`과 같은지 검사합니다. 같으면 위쪽(true), 다르거나 헤더가 없으면 아래쪽(false) 출력으로 갑니다.
3. **Respond 200:** `{ok: true, echo: <본문의 text>}`를 상태 코드 200으로 돌려줍니다.
4. **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의 자격 증명 저장소를 연결합니다. 이 글에서는 자격 증명 방식을 시험하지 않았습니다.

파이썬에서 부르려면 이렇게 합니다.

```python
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`

```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`

```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` 볼륨만 지웁니다.

![run_n8n.sh 실행 결과에서 컨테이너가 running이고 두 워크플로가 가져와져 목록에 나오며, hello-webhook은 200과 404를, guarded-webhook은 맞는 토큰에 200, 틀린 토큰과 토큰 없음에 401을 돌려주고, 마지막에 컨테이너와 볼륨이 삭제되는 것을 확인합니다.](https://copyandrun.com/img/n8n-docker-webhook-workflow/05-전체-스크립트-결과.png)

```bash
#!/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)를 처음부터 끝까지 두 번 실행했고, 매번 끝난 뒤 컨테이너와 볼륨을 삭제했습니다.
- **해 보지 않은 것:** 웹 화면에서 노드 편집, 외부 서비스 연동, 인증 설정, 게시 전의 호출 결과, 업그레이드. 화면 캡처는 같은 구성을 다시 띄워 관리자 계정을 만든 뒤 찍었고, 첫 접속 때 나오는 설문 창은 닫고 캡처했습니다.
- **읽을 때 주의:** 워크플로 파일은 직접 만든 최소 예시입니다.
