Webhook 트리거 — 외부 이벤트 수신

🎯 학습 목표

이 강을 마치면 다음을 할 수 있습니다.

• n8n Webhook 노드로 고유 URL을 생성하고 외부 서비스에 등록합니다.
• GET·POST 요청을 수신해 데이터를 처리하는 워크플로우를 구성합니다.
• Respond to Webhook 노드로 외부 서비스에 즉시 응답을 반환합니다.
• GitHub Push 이벤트 수신 실전 패턴을 직접 구현할 수 있습니다.

💡 Webhook이란 무엇이고 왜 필요한가

이 섹션에서는 Webhook의 개념과 스케줄 트리거와의 차이점을 살펴보겠습니다.

Webhook은 "이벤트가 발생했을 때 특정 URL로 HTTP 요청을 보내 알려주는" 방식입니다. 비유하자면 전화와 같습니다. 상대방이 연락이 있을 때 먼저 전화해 주는 방식입니다. 이와 반대로 주기적으로 API를 호출해서 "변경사항이 있나요?"라고 확인하는 방식을 폴링(Polling)이라고 합니다. 이는 매 5분마다 상대방에게 전화해서 확인하는 것과 같습니다. Webhook은 폴링에 비해 실시간성이 높고, 불필요한 API 호출이 없어 효율적입니다.

현대의 거의 모든 SaaS 서비스는 Webhook을 지원합니다. GitHub는 코드가 Push될 때, Stripe는 결제가 완료될 때, Shopify는 주문이 생성될 때 설정한 URL로 이벤트를 전송합니다. n8n의 Webhook 노드는 이러한 외부 이벤트를 수신해 워크플로우를 즉시 실행시키는 역할을 합니다. Webhook 트리거를 활용하면 "X 서비스에서 Y 이벤트가 발생하면 Z 작업을 즉시 한다"는 실시간 자동화를 구현할 수 있습니다.

🔧 Webhook 노드 설정과 URL 생성

이 섹션에서는 n8n에서 Webhook URL을 만들고 설정하는 방법을 살펴보겠습니다.

Webhook 노드를 캔버스에 추가하면 즉시 고유한 URL이 생성됩니다. URL 형식은 https://[n8n-도메인]/webhook/[고유-경로]입니다. 클라우드 n8n이면 https://[계정명].app.n8n.cloud/webhook/... 형태가 됩니다. 셀프호스팅이면 여러분의 도메인이 사용됩니다. 이 URL을 외부 서비스에 등록하면 됩니다.

Webhook 노드에서 설정할 주요 옵션을 살펴보겠습니다.

옵션	설명	기본값
HTTP Method	수신할 HTTP 메서드 (GET, POST, PUT, DELETE, ANY)	GET
Path	URL의 고유 경로 부분	자동 생성 UUID
Authentication	요청 인증 방식 (None, Basic Auth, Header Auth)	None
Response Mode	응답 방식 (즉시/워크플로우 완료 후)	즉시

HTTP Method는 대부분의 Webhook에서 POST를 사용합니다. 외부 서비스가 JSON Body에 이벤트 데이터를 담아 POST 요청을 보내기 때문입니다. Path는 자동 생성된 UUID를 그대로 사용해도 되고, 가독성을 위해 의미 있는 이름(예: github-push)으로 바꿀 수도 있습니다. 단, 경로가 노출되면 아무나 워크플로우를 트리거할 수 있으므로, 중요한 워크플로우에는 반드시 Authentication을 설정하십시오.

Webhook 노드를 포함한 워크플로우를 활성화하면 URL이 "Production URL"로 전환됩니다. 활성화 전의 URL은 "Test URL"로, 테스트 실행에서만 사용됩니다. 외부 서비스에는 반드시 Production URL을 등록해야 합니다.

🧪 GET/POST 수신 테스트 — curl로 직접 확인하기

이 섹션에서는 curl 명령으로 Webhook URL을 직접 테스트하는 방법을 살펴보겠습니다.

외부 서비스에 등록하기 전에 Webhook이 제대로 수신되는지 먼저 테스트해야 합니다. 가장 간단한 방법은 curl 명령입니다. n8n에서 워크플로우를 "Test" 모드로 실행한 상태에서 터미널에서 다음 명령을 실행합니다.

GET 요청 테스트:

curl -X GET "https://[n8n-도메인]/webhook-test/[경로]?name=홍길동&action=login"

POST 요청 테스트:

curl -X POST "https://[n8n-도메인]/webhook-test/[경로]"   -H "Content-Type: application/json"   -d '{"event":"push","repository":"my-repo","pusher":"hong"}'

curl을 실행하면 n8n 캔버스에서 Webhook 노드가 데이터를 수신하고, 노드 오른쪽에 데이터 미리보기가 나타납니다. GET 요청의 쿼리 파라미터는 {{ $json.query.name }}으로, POST 요청의 Body 데이터는 {{ $json.body.event }}처럼 접근합니다. Postman이나 Insomnia 같은 API 테스트 도구를 사용해도 됩니다.

↩️ Respond to Webhook 노드

이 섹션에서는 Webhook 요청에 응답을 반환하는 방법을 살펴보겠습니다.

외부 서비스는 Webhook을 보낸 후 응답을 기다립니다. 응답이 없거나 너무 늦으면 타임아웃 오류를 냅니다. n8n의 Respond to Webhook 노드를 사용하면 워크플로우 중간에 즉시 응답을 반환할 수 있습니다. 이렇게 하면 외부 서비스는 신속하게 응답을 받고, n8n은 백그라운드에서 나머지 처리를 계속합니다.

Respond to Webhook 노드에서는 응답 상태 코드(200, 201, 400 등)와 응답 Body를 설정합니다. 예를 들어 GitHub의 Webhook은 200 응답을 받아야 성공으로 처리합니다. 간단한 경우에는 {"status": "received"}같은 최소한의 응답을 반환합니다. Stripe 같은 서비스는 응답 형식이 정해져 있으므로, 해당 문서를 확인해 형식을 맞춰야 합니다.

Webhook 노드의 "Response Mode" 옵션도 관련이 있습니다. "Respond Immediately"로 설정하면 데이터 수신 즉시 200 응답을 반환하고 나머지 처리는 비동기로 진행합니다. "Last Node"로 설정하면 워크플로우 마지막 노드의 출력을 응답으로 반환합니다. 처리 시간이 길거나 비동기 처리가 필요한 경우 Respond Immediately + Respond to Webhook 조합이 권장됩니다.

💻 실전: GitHub Push 이벤트 수신

이 섹션에서는 GitHub에서 코드가 Push될 때 자동으로 슬랙에 알림을 보내는 실전 워크플로우를 살펴보겠습니다.

목표: main 브랜치에 코드가 Push되면 슬랙 #dev-alerts 채널에 "저장소명 / 작성자 / 커밋 메시지"를 알림으로 보냅니다.

워크플로우 구성 순서는 다음과 같습니다. 먼저 n8n에서 Webhook 노드(POST, 경로: github-push)를 추가하고 활성화합니다. Production URL을 복사합니다. GitHub 저장소 → Settings → Webhooks → Add webhook으로 이동해 Payload URL에 복사한 URL을 입력하고, Content type을 "application/json", 이벤트를 "Just the push event"로 선택합니다. 저장 후 GitHub가 테스트 Ping을 전송합니다.

n8n 워크플로우에서 IF 노드를 추가합니다. 조건: {{ $json.body.ref }}가 "refs/heads/main"과 같을 때만 처리(main 브랜치 Push만 알림). 조건이 참이면 Slack 노드로 연결합니다. Slack 메시지 내용 예시:

📦 *{{ $json.body.repository.name }}* 에 Push 발생
👤 작성자: {{ $json.body.head_commit.author.name }}
💬 커밋: {{ $json.body.head_commit.message }}
🔗 {{ $json.body.head_commit.url }}

Respond to Webhook 노드를 IF 노드의 false 경로와 Slack 노드 이후 모두에 연결해 어떤 경우든 GitHub에 즉시 200 응답을 반환합니다. 이 워크플로우가 활성화되면, main에 Push가 일어날 때마다 슬랙에 자동 알림이 옵니다.

📝 핵심 요약

개념	핵심 내용
Webhook vs 폴링	Webhook은 이벤트 발생 시 즉시 푸시. 폴링보다 실시간·효율적
Test URL vs Production URL	외부 서비스에는 반드시 Production URL 등록
데이터 접근	GET 쿼리: $json.query.키 / POST Body: $json.body.키
Respond to Webhook	외부 서비스 타임아웃 방지. 즉시 200 응답 후 백그라운드 처리
보안	중요 Webhook에는 Header Auth 또는 HMAC 서명 검증 필수

다음 강에서는 스케줄 트리거를 살펴봅니다. Cron 표현식으로 정해진 시각에 자동으로 실행되는 워크플로우를 설계하면, 매일 아침 리포트 발송, 주간 데이터 집계 같은 정기 작업을 완전히 자동화할 수 있습니다.