webhook (웹훅) 노드에 대해 알아보자
n8n 웹훅은 외부 애플리케이션이나 서비스에서 n8n 워크플로우를 트리거하도록 해주는 특수한 URL입니다. 🎣 마치 특정 이벤트가 발생했을 때 n8n 워크플로우를 실행시키기 위한 '입구' 역할을 한다고 생각할 수 있습니다.
hook은 낚아챈다는 의미죠? 따라서 웹에서 어떤 이벤트가 발생해서 n8n으로 보내지면 그 이벤트를 낚아채서 n8n에서 작성된 워크플로우를 구동한다는 의미로 보시면 될것 같습니다.
웹훅의 주요 장점
실시간 처리: 이벤트가 발생한 즉시 워크플로우가 실행되므로 실시간 데이터 처리가 가능합니다. ⏰
자원 효율성: API를 주기적으로 호출하여 데이터를 확인하는 폴링(polling) 방식과 달리, 웹훅은 이벤트가 있을 때만 작동하므로 서버 자원을 효율적으로 사용합니다.
단순성: 설정이 비교적 간단하고, 대부분의 최신 서비스가 웹훅 기능을 지원합니다.
웹훅의 작동 원리
웹훅은 '콜백(callback)' 개념을 사용합니다. 일반적인 API 요청-응답 방식이 클라이언트가 서버에 데이터를 요청하고 응답을 받는 방식이라면, 웹훅은 이벤트가 발생했을 때 서버가 클라이언트에 데이터를 '푸시(push)'하는 방식입니다.
예를 들어, GitHub에 새로운 커밋이 발생하면 GitHub 서버가 미리 설정된 n8n 웹훅 URL로 데이터를 전송합니다. n8n은 이 데이터를 수신하여 미리 정의된 워크플로우(예: Slack으로 알림 보내기, 스프레드시트에 기록하기 등)를 실행하는 식입니다. 🚀
웹훅 노드는 n8n에서 이 기능을 담당하며, 다음과 같은 주요 설정으로 구성됩니다.
웹훅 URL: n8n이 생성하는 고유한 주소로, 외부 서비스에 이 URL을 등록하여 이벤트를 수신합니다.
HTTP 메서드: GET, POST, PUT 등 웹훅이 어떤 HTTP 요청을 받을지 지정합니다. 일반적으로는 데이터를 안전하게 전송하기 위해 POST 메서드를 사용합니다.
JSON/Binary 데이터 처리: 웹훅을 통해 들어오는 데이터 형식을 설정합니다. 대부분의 경우 JSON 형식을 사용합니다.
n8n의 웹훅은 테스트를 위한 Test URL 부분과 실제 운영을 위한 Production URL 부분으로 나뉘게 되는데요. 테스트는 그야말로 테스트 환경에서만 사용할 수 있는 URL입니다. 실제 자동화 운영시에는 옆에 보이는 Production URL 부분으로 이벤트가 날라와야 합니다.
URL을 보시면 중간 webhoob-test와 webhook 부분이 다른 것을 보실 수 있는데요. 실제 자동화 운영시에는 webhook이 들어 있는 Production URL 부분을 사용해서 외부 웹에서 Production URL로 이벤트를 보내야 제대로 동작합니다. 이벤트를 보낸다는 건 웹 주소를 브라우저에 입력하고 Enter를 입력하면 이벤트가 n8n으로 날아간다는 의미입니다.
또한 현재는 셀프호스트를 사용중이므로 localhost로 되어 있습니다만...실제 운영시에는 localhost로는 이벤트가 오지 않으므로 도메인 주소 혹은 외부에서 접속 가능한 IP주소가 기입되어야 합니다.
IP주소를 입력하면 외부에 내 IP주소가 노출되므로 통상 도메인을 구입해서 내 셀프호스트에 적용해서 도메인주소로 들어오도록 하는 것이 좋겠죠?
웹훅 설정 옵션들
Path (경로)
Path는 웹훅 URL의 고유한 경로 부분입니다. 이 필드에 입력한 값은 최종 웹훅 URL의 끝에 추가됩니다. 예를 들어, n8n 인스턴스 URL이 https://your-n8n.com이고 여기에 my-data를 입력하면, 최종 웹훅 URL은 https://your-n8n.com/webhook/my-data가 됩니다. 이 경로를 통해 여러 웹훅을 구분할 수 있습니다. 🛤️
Authentication (인증)
None (없음)
별도의 인증 절차가 필요 없습니다. 웹훅 URL을 아는 사람이라면 누구나 워크플로우를 실행할 수 있습니다. 기본 디폴트는 None으로 설정되어 있습니다.
사용 사례: 공개적으로 데이터를 받는 워크플로우(예: 공개 설문지 제출) 또는 보안이 크게 중요하지 않은 경우에 사용됩니다.
Basic Auth (기본 인증)
HTTP 기본 인증 방식을 사용합니다. 웹훅을 호출할 때 사용자 이름과 비밀번호를 함께 보내야 합니다.
사용 사례: 비교적 간단하게 웹훅을 보호하고 싶을 때 사용합니다. 예를 들어, 일부 레거시 시스템이나 간단한 스크립트에서 워크플로우를 호출할 때 유용합니다.
Header Auth (헤더 인증)
HTTP 헤더에 특정 키와 값을 포함시켜야만 웹훅 호출이 허용됩니다. 예를 들어, X-Api-Key라는 헤더에 미리 정해둔 비밀 값을 담아 보내야 합니다.
사용 사례: GitHub, Stripe 등 대부분의 현대적인 웹 서비스에서 웹훅 보안을 위해 널리 사용되는 방법입니다. 공유된 비밀 키를 이용해 안전하게 호출자를 확인합니다.
JWT Auth (JWT 인증)
JSON Web Token을 사용합니다. 요청 시 유효한 JWT 토큰을 함께 보내야 하며, n8n이 이 토큰의 서명을 검증하여 호출자의 신뢰성을 확인합니다.
사용 사례: 가장 강력한 보안을 제공하는 방법입니다. 호출자의 신원과 데이터 무결성을 동시에 검증해야 할 때 사용됩니다. 복잡하지만, 가장 안전한 워크플로우 보호 방법입니다.
Respond (응답)
이 이미지는 n8n 웹훅 노드의 응답(Respond) 옵션을 보여줍니다. 이 옵션은 외부 서비스로부터 웹훅 호출을 받았을 때 n8n이 어떻게 응답을 보낼지를 결정합니다. 📨
Immediately (즉시)
웹훅 요청을 받는 즉시, 워크플로우 실행이 끝나기를 기다리지 않고 바로 HTTP 200 OK와 같은 성공 응답을 보냅니다. 기본 디폴트는 Immediately로 설정되어 있습니다.
장점: 웹훅을 호출한 서비스는 워크플로우의 실행 시간에 영향을 받지 않고 빠르게 응답을 받을 수 있습니다.
사용 사례: 워크플로우가 오래 걸릴 수 있거나, 호출한 서비스에 별도의 응답 데이터를 보낼 필요가 없을 때 유용합니다.
When Last Node Finishes (마지막 노드가 완료될 때)
워크플로우의 마지막 노드 실행이 완료될 때까지 기다린 후, 마지막 노드의 출력 데이터를 응답 본문으로 보냅니다. 응답 코드는 기본적으로 200 OK입니다.
장점: 워크플로우의 최종 결과를 웹훅을 호출한 서비스에 직접 전달할 수 있습니다.
사용 사례: 웹훅을 호출하여 특정 작업을 수행하고, 그 결과(예: 생성된 파일의 URL, 처리된 데이터)를 즉시 받아야 할 때 사용합니다.
Using 'Respond to Webhook' Node ('웹훅에 응답' 노드 사용)
이 옵션을 선택하면 웹훅 노드 자체에서는 응답을 보내지 않고, 워크플로우 내의 다른 곳에 있는 'Respond to Webhook' 노드를 사용해 응답을 제어합니다.
장점: 워크플로우 실행 중에 특정 조건(예: 데이터 유효성 검사 실패)에 따라 다른 응답을 보내거나, 여러 조건부 응답을 설정할 수 있어 유연성이 매우 높습니다.
사용 사례: 복잡한 워크플로우에서 조건에 따라 응답을 다르게 해야 할 때(예: 성공 시 200, 실패 시 400 에러 코드 반환) 사용합니다.
Options (옵션)
n8n 웹훅 노드의 추가 옵션(Options) 목록을 보여줍니다. 이 옵션들은 웹훅의 동작을 더 세밀하게 제어하는 데 사용됩니다. ⚙️
Allowed Origins (CORS)
CORS (교차 출처 리소스 공유) 정책을 설정합니다. 특정 도메인(출처)에서 오는 요청만 웹훅에 접근하도록 허용합니다.
사용 사례: 웹 브라우저에서 실행되는 프론트엔드 애플리케이션(예: 리액트 앱)이 웹훅을 호출할 때 보안 문제를 해결하기 위해 사용합니다. *를 설정하면 모든 출처를 허용합니다.
Field Name for Binary Data
바이너리 데이터(예: 파일)가 웹훅으로 전송될 때, n8n이 데이터를 저장할 필드 이름을 지정합니다.
사용 사례: 웹훅을 통해 이미지나 문서 파일 등을 받을 때, 워크플로우에서 해당 파일 데이터를 쉽게 참조할 수 있도록 이름을 설정합니다.
Ignore Bots (봇 무시)
웹훅 요청이 스팸 봇으로부터 온 것으로 의심될 경우, 이를 자동으로 무시하고 워크플로우를 실행하지 않습니다.
사용 사례: 공개 웹훅 URL을 사용하지만, 스팸성 트래픽을 차단하여 불필요한 워크플로우 실행을 막고 싶을 때 유용합니다.
IP(s) Whitelist (IP 화이트리스트)
특정 IP 주소 또는 IP 범위에서 오는 요청만 웹훅 호출을 허용합니다.
사용 사례: 내부망에서만 호출되거나, 특정 서버에서만 요청이 올 것으로 예상되는 경우에 사용합니다. 매우 강력한 보안 제어 방법입니다.
No Response Body (응답 본문 없음)
웹훅 응답에 본문 데이터를 포함하지 않고, 헤더와 상태 코드만 보냅니다.
사용 사례: 호출한 서비스에 응답 데이터가 필요 없거나, 응답 크기를 최소화하고 싶을 때 사용합니다.
Raw Body (원시 본문)
웹훅 요청의 본문 데이터를 JSON으로 파싱하지 않고, 원시(raw) 텍스트 또는 바이너리 형태로 받습니다.
사용 사례: JSON 형식이 아닌, XML, CSV 등 다른 형식의 데이터를 웹훅으로 받을 때 유용합니다.
Response Code (응답 코드)
웹훅 요청에 대한 HTTP 응답 코드를 설정합니다. 예를 들어, 200 (OK), 400 (Bad Request), 500 (Internal Server Error) 등을 지정할 수 있습니다.
사용 사례: 웹훅 호출 성공 또는 실패 여부를 호출한 서비스에 명확하게 알려주기 위해 사용합니다.
Response Data (응답 데이터)
웹훅 응답 본문에 포함될 데이터를 직접 입력합니다. JSON, HTML, 일반 텍스트 등 다양한 형식을 지원합니다.
사용 사례: 워크플로우 실행과 관계없이 웹훅 호출에 대해 특정 메시지(예: "성공적으로 수신되었습니다")를 보내고 싶을 때 사용합니다.
n8n 웹훅 활용 사례
이커머스: Shopify에서 새로운 주문이 발생했을 때 웹훅을 통해 n8n으로 데이터를 보내고, 이를 ERP 시스템에 자동으로 기록하고 고객에게 확인 이메일을 발송합니다.
소셜 미디어 관리: 새로운 인스타그램 댓글이 달리면 웹훅으로 이를 감지하고, 해당 댓글을 구글 스프레드시트에 자동으로 추가합니다.
CS 자동화: Zendesk에 새로운 티켓이 생성되면 웹훅을 통해 n8n으로 전달하고, 담당자에게 Slack 알림을 보냅니다.
데이터 동기화: GitHub에 코드 변경이 발생하면 웹훅을 통해 n8n이 트리거되어 변경 사항을 다른 개발 도구와 동기화합니다.