AI/Technical

n8n 사용법 실무 가이드: Webhook·스케줄·에러처리 3종 워크플로우

Royzero 2026. 1. 6. 08:55
반응형

TL;DR

  • n8n은 “트리거(Trigger) → 처리(Transform) → 액션(Action)”을 노드로 조립해 자동화를 만드는 도구다.
  • Webhook 기반 이벤트 자동화는 인증/서명 검증과 응답(Respond) 설계를 먼저 잡아야 운영이 편해진다.
  • 스케줄 기반 수집은 HTTP Request의 Pagination과 Loop Over Items(구 Split in Batches)로 레이트리밋/대량 처리를 안정화한다.
  • 운영에서는 에러 워크플로우(Error Trigger)와 Stop And Error로 실패를 "관측 가능한 이벤트"로 만드는 것이 핵심이다.

본문

1. n8n 기본 개념을 “실무 관점”으로 재정리

1.1 워크플로우, 노드, 아이템(Item)

  • 워크플로우는 노드들의 연결 그래프이며, 노드는 입력 아이템 리스트를 처리하는 형태가 기본이다. Loop Over Items 문서에서도 "기본적으로 n8n 노드는 아이템 리스트를 처리"한다고 전제한다.
  • 실무에서 중요한 건 “아이템이 몇 개인지”와 “어떤 필드가 어디에 있는지”다. Webhook/HTTP 요청처럼 외부 입력이 들어오면, 첫 노드 출력 구조를 고정(정규화)해두면 뒤가 편해진다.

1.2 Cloud vs Self-host에서 달라지는 포인트(코드/보안/운영)

  • Code 노드에서 사용할 수 있는 모듈은 환경에 따라 다르다. n8n Cloud에서는 기본적으로 crypto, moment만 사용 가능하다고 명시돼 있다.
  • Self-host는 환경 변수로 Code 노드에서 사용할 모듈을 활성화할 수 있다.
  • Webhook는 운영 URL/테스트 URL이 분리된다. 테스트 URL은 "Test step"을 실행한 뒤 120초 동안만 활성이라고 문서에 명시돼 있다.

Why it matters: 실무 자동화는 "만드는 것"보다 "운영 중 망가지지 않게 하는 것"이 더 어렵다. Cloud/Self-host 차이를 모르고 설계하면, 배포 후에 코드가 안 돌거나(모듈 제한), Webhook이 외부에서 안 들어오거나(리버스 프록시/URL 설정) 같은 문제로 시간을 크게 쓴다.

2. 실습 워크플로우 #1: GitHub Webhook 수신 → 서명 검증 → Slack 알림 → 응답

2.1 목표 시나리오

  • GitHub에서 issues 이벤트(예: opened)가 발생하면 n8n이 Webhook로 받는다.
  • X-Hub-Signature-256을 이용해 GitHub 발송/변조 여부를 검증한다. GitHub는 HMAC hex digest를 쓰며, 서명은 sha256=로 시작한다고 명시한다.
  • 검증 성공 시 Slack에 요약 알림을 보내고, 실패 시 401로 응답한다.

2.2 전체 흐름(다이어그램)

flowchart LR
  A[Webhook Trigger] --> B[Signature Verify (Code/Crypto)]
  B -->|valid| C[Normalize Fields (Edit Fields/Set)]
  C --> D[Send Slack Message]
  D --> E[Respond to Webhook 200]
  B -->|invalid| F[Respond to Webhook 401]

2.3 노드 구성 체크리스트(요약 표)

순서 노드 핵심 설정 포인트
1 Webhook Method=POST, Path=/github/issues, Raw Body 옵션 서명 검증은 “원문 바디”가 필요 ([n8n Docs][1])
2 Code 또는 Crypto HMAC-SHA256 계산 + timing-safe 비교 GitHub는 단순 == 비교 대신 constant-time 비교를 권장 ([GitHub Docs][7])
3 Edit Fields(Set) 필요한 필드만 남기기/이름 정리 후속 노드 안정화 ([n8n Docs][8])
4 Slack 채널/메시지 템플릿 운영 알림 표준화 ([Baserow][9])
5 Respond to Webhook 성공 200 / 실패 401 Webhook 응답을 워크플로우에서 통제 ([n8n Docs][10])

2.4 Webhook 노드: “Raw Body + 인증”을 먼저 잡기

Webhook 노드에는 다음이 중요하다.

  1. Raw Body 옵션 활성화
    GitHub 서명 검증은 "payload contents(요청 바디 원문)" 기반이므로, n8n에서도 Raw Body를 보존해야 한다. Webhook 문서에 Raw Body 옵션이 명시돼 있다.

  2. 인증 옵션 적용
    Webhook 노드는 Basic Auth / Header Auth / JWT 등 인증 방식을 제공한다(외부에서 직접 때리는 엔드포인트라면 최소 1개는 권장).

  3. 최대 페이로드 제한 확인
    Webhook 기본 최대 페이로드는 16MB이며 N8N_PAYLOAD_SIZE_MAX로 변경 가능하다고 명시돼 있다.

2.5 GitHub 서명 검증: Code 노드 예시(Cloud에서도 crypto 가능)

GitHub 문서가 말하는 핵심은 3가지다.

  • X-Hub-Signature-256 헤더를 받는다(비밀키 설정을 안 하면 헤더가 없을 수 있음).
  • HMAC-SHA256으로 sha256=<hex> 형식 서명을 직접 계산한다.
  • == 대신 timing-safe 비교를 권장한다.

n8n에서 구현할 때는 Webhook 노드 실행 결과에서 “Raw body 필드”와 “headers 필드”가 무엇인지를 먼저 확인하자(테스트 실행 후 Webhook 노드 OUTPUT에서 키를 확인). 그 키를 아래 코드의 RAW_BODY_PATH, SIG_HEADER_PATH에 맞게 읽으면 된다.

// n8n Code node (JavaScript)
// 전제: Webhook 노드에서 Raw Body 옵션을 켰고, Output에 raw body(문자열)와 headers가 존재한다.

const crypto = require('crypto');

// 1) 아래 2개는 Webhook 노드 OUTPUT 구조에 맞게 바꿔야 함
const rawBody = $json.rawBody ?? $json.body ?? ''; // 예시: rawBody 키가 다를 수 있음
const sigHeader =
  ($json.headers?.['x-hub-signature-256']) ||
  ($json.headers?.['X-Hub-Signature-256']) ||
  '';

// 2) n8n Credential 또는 env/vars로 관리 권장(하드코딩 금지)
const secret = $vars.GITHUB_WEBHOOK_SECRET; // 예시: n8n 변수 사용

if (!sigHeader) {
  return [{ json: { ok: false, reason: 'missing_signature_header' } }];
}

const hmac = crypto.createHmac('sha256', secret);
hmac.update(rawBody, 'utf8');
const expected = `sha256=${hmac.digest('hex')}`;

// timing-safe compare
const a = Buffer.from(expected, 'utf8');
const b = Buffer.from(sigHeader, 'utf8');

const ok = (a.length === b.length) && crypto.timingSafeEqual(a, b);

return [{ json: { ok, expected, received: sigHeader } }];
  • 위 코드처럼 timing-safe 비교는 GitHub 문서에서도 권장한다.
  • Crypto 노드를 써도 된다(해시/HMAC 계산 기능 제공).

2.6 Respond to Webhook로 “성공/실패 응답”을 분리

Webhook는 호출 측(GitHub)이 "응답 코드"를 보고 재시도/실패 처리를 한다. 그래서 n8n에서도 응답을 명시적으로 통제하는 편이 운영에 좋다. Respond to Webhook 노드는 이 목적의 코어 노드로 문서가 제공된다.

  • valid 경로: 200 { "status": "ok" }
  • invalid 경로: 401 { "status": "unauthorized" }

Why it matters: Webhook 자동화는 "보안(서명/인증) + 응답(200/401/500) + 관측(로그/알림)" 3가지를 같이 설계해야 실제 운영에서 안전하다. GitHub도 서명 검증을 통해 MITM/변조를 방지하라고 명시한다.

3. 실습 워크플로우 #2: 스케줄 기반 API 수집(페이지네이션) → 배치 처리 → 저장

3.1 목표 시나리오

  • 매일/매시간 외부 API에서 데이터(예: 주문/이슈/로그)를 가져온다.
  • API가 페이지네이션을 제공하면 HTTP Request 노드의 Pagination 기능을 활용한다.
  • 대량 아이템은 Loop Over Items(구 Split in Batches)로 나눠 처리하고, 종료 조건(termination condition)을 반드시 둔다(무한 루프 방지).

3.2 전체 흐름(다이어그램)

flowchart LR
  A[Schedule Trigger] --> B[HTTP Request (Pagination)]
  B --> C[Loop Over Items (Batch)]
  C --> D[Transform/Validate]
  D --> E[(DB Upsert/Insert)]
  E --> F[Slack Summary]

3.3 HTTP Request Pagination: 실무에서 필요한 “딱 2가지”

  1. Pagination 모드 선택
    HTTP Request 노드의 Pagination은 여러 모드를 제공한다(예: next URL 기반, offset/limit 기반 등).

  2. HTTP node 전용 변수 활용
    Pagination 설정은 "HTTP Request 노드 내부 표현식"에서만 쓸 수 있는 $pageCount, $request, $response 같은 변수를 제공한다.

예를 들어 “page 파라미터를 1부터 증가”시키는 식이라면(서비스가 이런 방식을 제공할 때), Pagination 설정에서 $pageCount를 이용해 다음 페이지 값을 만들 수 있다. (정확한 파라미터 이름은 대상 API 문서에 맞춘다.)

3.4 Loop Over Items(구 Split in Batches): 무한 루프 방지 규칙

Loop Over Items 문서는 다음을 명확히 말한다.

  • Batch Size로 한 번에 내보낼 아이템 개수를 정한다.
  • Reset 옵션과 If 노드를 조합해 “페이지를 1장씩 가져오며 처리” 같은 루프를 구성할 수 있다.
  • 유효한 종료 조건(termination condition)이 없으면 무한 루프에 빠질 수 있다.

실무 팁(안전한 종료 조건 예시)

  • (페이지 기반) “이번 호출 결과가 빈 배열이면 종료”
  • (next URL 기반) “next가 null/빈 문자열이면 종료”
  • (아이템 기반) “처리한 아이템 수가 목표치에 도달하면 종료”

3.5 실행 데이터(Execution data) 관리: 대량 수집 워크플로우의 숨은 비용

대량 수집 워크플로우는 실행 데이터가 쌓이면서 저장소/DB 비용이 커진다. n8n은 execution data pruning(실행 데이터 정리)을 지원하며, 기본적으로 활성화되어 있다는 문서가 있다.

Why it matters: 스케줄 수집은 "잘 돌아가는 것"보다 "계속 돌아가게 만드는 것"이 중요하다. Pagination/배치/종료조건/실행데이터 정리를 같이 설계해야, 레이트리밋·메모리·저장소 이슈로 멈추는 일을 줄일 수 있다.

4. 실습 워크플로우 #3: 에러 워크플로우(Error Workflow)로 실패를 표준화

4.1 에러 워크플로우의 핵심

n8n 문서는 "각 워크플로우마다 Error workflow를 지정할 수 있고, 실행이 실패하면 그 에러 워크플로우가 실행된다"고 설명한다. 에러 워크플로우는 반드시 Error Trigger로 시작해야 한다.

즉, 실무에선 아래를 표준으로 가져가면 좋다.

  • 모든 운영 워크플로우는 동일한 “Error Handler” 워크플로우를 참조한다.
  • Error Handler는 Slack/Email/이슈 트래커 중 최소 1곳으로 알림을 보낸다.
  • 알림 메시지 포맷을 통일한다(워크플로우명, 실패 노드, 실행 URL, 에러 메시지).

4.2 Error Trigger가 주는 데이터(실무에서 가장 유용한 필드)

에러 핸들링 문서에는 Error Trigger가 전달하는 기본 데이터 예시가 포함되어 있다. 예시 필드에는 execution.id, execution.url, execution.error.message, execution.lastNodeExecuted, workflow.id, workflow.name 등이 있다.

이를 그대로 Slack 메시지에 꽂으면 “원인 파악 시간”이 줄어든다.

4.3 Stop And Error로 “의도적 실패”를 만들기

Stop And Error 노드는 "커스텀 에러 메시지를 표시하고, 특정 조건에서 실행을 실패시키며, 에러 워크플로우로 커스텀 에러 정보를 보낼 수 있다"고 명시한다.

실무 예시

  • 서명 검증 실패를 "401 응답 + Stop And Error"로 처리해 보안 이벤트를 에러 워크플로우에서 집계
  • 데이터 품질 검사 실패(필수 필드 누락)를 Stop And Error로 종료 → Slack에 "데이터 계약 위반" 알림

Why it matters: 자동화에서 진짜 문제는 "실패했는데 아무도 모르는 상태"다. Error workflow + Stop And Error로 실패를 표준 이벤트로 만들면, 재발 방지(룰/모니터링/리트라이)까지 이어지는 루프를 만들 수 있다.

5. 운영(Production) 필수 체크: URL·큐 모드·메트릭·보안 점검

5.1 리버스 프록시/도메인 환경에서 Webhook URL 고정

Self-host에서 리버스 프록시 뒤에 둘 때는 Webhook URL 관련 설정을 문서에서 안내한다. (예: WEBHOOK_URL 설정)

Webhook URL이 어긋나면 GitHub 같은 외부 시스템이 “다른 주소로 Webhook을 보내는” 문제가 생긴다.

5.2 큐 모드(Queue mode)로 확장: Redis + 워커 + 암호화 키

n8n은 "Configuring queue mode" 문서로 큐 모드 설정을 안내한다.
또한 워커가 동작하려면 암호화 키가 동일해야 하는데, n8n은 N8N_ENCRYPTION_KEY를 커스텀으로 설정할 수 있고, 여러 인스턴스/워커에서 동일 키 사용이 필요하다는 맥락을 문서에서 제공한다.

5.3 Prometheus 메트릭과 보안 감사(audit)

  • Prometheus 메트릭 활성화는 문서에서 안내하며, 예: N8N_METRICS 및 /metrics 엔드포인트 제공을 포함한다.
  • 보안 감사(Security audit)는 "security audit로 리스크를 식별"할 수 있다고 안내한다.

5.4 보안 베이스라인(최소 권장)

  • n8n 문서는 보안 강화를 위해 SSL 설정, SSO/2FA, API 비활성화 등 옵션을 개요로 제시한다.
  • 일반적인 웹서비스 보안 베이스라인(HTTPS 강제, 인증/인가, 입력 검증 등)은 OWASP 가이드라인에서 반복적으로 강조된다.

Why it matters: 자동화는 "내부 편의 기능"처럼 보이지만, 실제로는 외부 입력(Webhook)과 내부 권한(Credentials)을 연결하는 통로다. URL/확장/관측/보안 점검을 운영 체크리스트로 갖고 가는 순간, 장애와 보안 리스크가 눈에 띄게 줄어든다.

결론 (요약 정리)

  • n8n 실무 자동화는 "Webhook(입력) / HTTP Request(수집) / Error workflow(운영)" 3축을 표준화하면 속도가 붙는다.
  • Webhook은 Raw Body 보존 + 서명 검증 + 응답 제어까지 한 번에 설계해야 안전하다.
  • 스케줄 수집은 Pagination + Loop Over Items 종료조건 + 실행데이터 관리로 "계속 도는 구조"를 만든다.
  • 에러 워크플로우는 실패를 관측 가능하게 만들고, Stop And Error로 의도적 실패까지 표준화할 수 있다.

References

반응형
저작자표시 비영리 변경금지 (새창열림)