웹훅

웹훅 (Webhook)

웹훅(Webhook) 노드는 앱·서비스에서 이벤트가 발생할 때 데이터를 받아올 수 있는 웹훅을 만들어요. 이 노드는 트리거 노드라서 n8n 워크플로를 시작할 수 있습니다. 덕분에 서비스가 n8n에 연결되어 워크플로를 실행할 수 있어요.

데이터를 받아 그 데이터를 기반으로 워크플로를 실행하고 싶을 때 웹훅 노드를 트리거로 쓸 수 있습니다. 웹훅 노드는 워크플로 끝에서 생성된 데이터를 반환하는 것도 지원해요. 데이터를 처리하고 결과를 돌려주는 워크플로, 즉 API 엔드포인트를 만드는 데 유용합니다.

전용 앱 트리거 노드가 없는 서비스에서 워크플로를 트리거할 때도 웹훅을 사용할 수 있어요.

워크플로 개발 과정

n8n은 테스트용과 프로덕션용으로 서로 다른 웹훅 URL을 제공합니다. 테스트 URL에는 테스트 이벤트 대기(Listen for test event) 옵션이 포함되어 있어요. 웹훅 노드를 만들고 테스트한 뒤 프로덕션으로 전환하는 방법은 워크플로 개발을 참고하세요.

노드 파라미터

이 파라미터들로 노드를 설정합니다.

웹훅 URL

웹훅 노드에는 테스트(Test) url과 프로덕션(Production) url, 두 개의 웹훅 URL이 있어요. n8n은 노드 패널 상단에 url을 표시합니다.

테스트 URL 또는 프로덕션 URL을 선택해 n8n이 표시할 URL을 전환할 수 있어요.

테스트(Test): 워크플로가 활성 상태가 아닐 때 테스트 이벤트 대기나 워크플로 실행(Execute workflow) 을 선택하면 n8n이 테스트 웹훅을 등록합니다. 웹훅 URL을 호출하면 n8n이 워크플로에 데이터를 표시해요.
프로덕션(Production): 워크플로를 게시하면 n8n이 프로덕션 웹훅을 등록합니다. 프로덕션 URL을 사용할 때 n8n은 워크플로에 데이터를 표시하지 않아요. 프로덕션 실행의 데이터를 보려면 워크플로에서 실행(Executions) 탭을 선택한 뒤 확인하고 싶은 실행을 고르면 됩니다.

HTTP 메서드

웹훅 노드는 표준 HTTP 요청 메서드를 지원합니다.

DELETE
GET
HEAD
PATCH
POST
PUT

웹훅 최대 페이로드

웹훅 최대 페이로드 크기는 16MB예요. 셀프호스팅이라면 엔드포인트 환경 변수N8N_PAYLOAD_SIZE_MAX로 이 값을 바꿀 수 있습니다.

경로(Path)

기본값은 다른 웹훅 노드와 충돌을 피하려고 무작위로 생성된 URL 경로입니다.

URL 경로를 직접 지정할 수 있는데, 라우트 파라미터를 추가하는 것도 가능해요. n8n으로 API를 프로토타이핑하면서 일관된 엔드포인트 URL이 필요할 때 주로 이렇게 합니다.

경로 필드는 다음 형식을 받을 수 있어요.

/:variable
/path/:variable
/:variable/path
/:variable1/path/:variable2
/:variable1/:variable2

지원되는 인증 방식

웹훅 URL을 호출하는 모든 서비스에 인증을 요구할 수 있어요. 다음 인증 방식 중에서 고릅니다.

Basic auth
Header auth
JWT auth
None

각 자격증명(credential) 유형 설정 방법은 웹훅 자격증명을 참고하세요.

응답(Respond)

즉시(Immediately): 웹훅 노드가 응답 코드와 Workflow got started 메시지를 돌려줍니다.
마지막 노드 완료 시(When Last Node Finishes): 웹훅 노드가 응답 코드와 워크플로에서 마지막으로 실행된 노드의 데이터 출력을 반환해요.
'Respond to Webhook' 노드 사용(Using 'Respond to Webhook' Node): 웹훅 노드가 Respond to Webhook 노드에 정의된 대로 응답합니다.
스트리밍 응답(Streaming response): 워크플로가 처리되는 동안 사용자에게 실시간 데이터 스트리밍을 활성화합니다. 워크플로에 스트리밍을 지원하는 노드(예: AI 에이전트 노드)가 필요해요.

응답 코드(Response Code)

성공적으로 실행됐을 때 웹훅 노드가 반환할 HTTP 응답 코드를 커스터마이즈합니다. 일반적인 응답 코드 중에서 고르거나, 커스텀 코드를 만들 수 있어요.

응답 데이터(Response Data)

응답 본문에 포함할 데이터를 고릅니다.

모든 항목(All Entries): 웹훅이 마지막 노드의 모든 항목을 배열로 반환해요.
첫 항목 JSON(First Entry JSON): 웹훅이 마지막 노드의 첫 항목 JSON 데이터를 JSON 객체로 반환합니다.
첫 항목 바이너리(First Entry Binary): 웹훅이 마지막 노드의 첫 항목 바이너리 데이터를 바이너리 파일로 반환해요.
응답 본문 없음(No Response Body): 웹훅이 본문 없이 반환합니다.

응답 > 마지막 노드 완료 시일 때만 적용됩니다.

노드 옵션

옵션 추가(Add Option) 를 선택하면 더 많은 설정 옵션을 볼 수 있어요. 사용 가능한 옵션은 노드 파라미터에 따라 달라지며, 아래 표를 참고하세요.

허용된 오리진(CORS)(Allowed Origins (CORS)): 허용할 크로스 오리진 도메인을 설정합니다. 크로스 오리진 non-preflight 요청에 허용되는 URL을 쉼표로 구분해 입력해요. *(기본값)로 두면 모든 오리진을 허용합니다.
바이너리 속성(Binary Property): 켜면 웹훅 노드가 이미지·오디오 파일 같은 바이너리 데이터를 받을 수 있어요. 받은 파일의 데이터를 쓸 바이너리 속성 이름을 입력합니다.
봇 무시(Ignore Bots): 링크 미리보기·웹 크롤러 같은 봇의 요청을 무시해요.
IP 허용 목록(IP(s) Allowlist): 웹훅 트리거 URL을 호출할 수 있는 대상을 제한할 때 켭니다. 허용할 IP 주소를 쉼표로 구분해 입력해요. 허용 목록에 없는 IP의 접근은 403 오류가 납니다. 비워 두면 모든 IP가 웹훅 트리거 URL을 호출할 수 있어요.
응답 본문 없음(No Response Body): n8n이 응답에 본문을 보내지 않게 할 때 켭니다.
이 경우에만 실행(Only Run If): 들어오는 요청에 대해 평가되는 표현식이에요. 표현식이 true를 반환할 때만 워크플로가 실행됩니다. 요청을 { body, headers, params, query }로 접근하려면 $json을 씁니다. 예: {{ $json.body.campaign_id === 'user-research-invite' }}. 조건에 맞지 않는 요청은 실행을 만들지 않고 200 응답을 받아요. 표현식 평가가 실패하면 n8n은 경고를 기록하고 요청을 차단하지 않고 통과시킵니다. 이 옵션은 IP 허용 목록과 인증 검사 이후에 적용되며, 테스트·프로덕션 웹훅 URL 모두에 적용돼요.
원시 본문(Raw Body): 웹훅 노드가 JSON이나 XML 같은 원시(raw) 형식으로 데이터를 받도록 지정합니다.
응답 콘텐츠 타입(Response Content-Type): 웹훅 본문의 형식을 고릅니다.
응답 데이터(Response Data): 응답과 함께 커스텀 데이터를 보냅니다.
응답 헤더(Response Headers): 웹훅 응답에 추가 헤더를 보내요. 응답 헤더에 대한 자세한 내용은 MDN 웹 문서 | 응답 헤더를 참고하세요.
속성 이름(Property Name): 기본적으로 n8n은 사용 가능한 모든 데이터를 반환합니다. 특정 JSON 키 하나를 골라 그 값만 반환하도록 할 수 있어요.

옵션	필요한 노드 구성
허용된 오리진(CORS)	모든
바이너리 속성	다음 중 하나: HTTP 메서드 > POST, PATCH, PUT
봇 무시	모든
IP 허용 목록	모든
이 경우에만 실행	모든
속성 이름	둘 다: 응답 > 마지막 노드 완료 시, 응답 데이터 > 첫 항목 JSON
응답 본문 없음	응답 > 즉시
원시 본문	모든
응답 코드	'Respond to Webhook' 노드 사용을 제외한 모든 응답
응답 콘텐츠 타입	둘 다: 응답 > 마지막 노드 완료 시, 응답 데이터 > 첫 항목 JSON
응답 데이터	응답 > 즉시
응답 헤더	모든

n8n이 HTML 응답을 보호하는 방식

기능 가용성

웹훅에 대한 HTML 응답을 <iframe> 태그로 자동 감싸는 기능은 n8n 1.103.0에서 도입됐어요.

n8n 1.103.0부터 n8n은 웹훅에 대한 HTML 응답을 자동으로 <iframe> 태그로 감쌉니다. 인스턴스 사용자를 보호하기 위한 보안 장치예요. 여기에는 다음 의미가 따라옵니다.

HTML이 부모 문서에 직접 렌더링되는 대신 샌드박스화된 iframe 안에서 렌더링됩니다.
최상위 창이나 로컬 스토리지에 접근하려는 JavaScript 코드는 실패해요.
샌드박스화된 iframe 안에서는 인증 헤더를 사용할 수 없습니다(예: basic auth). HTML 안에 단기 액세스 토큰을 임베드하는 방식 같은 대안을 써야 해요.
상대 URL(예: <form action="/">)은 동작하지 않습니다. 대신 절대 URL을 사용하세요.

템플릿과 예시

n8n-nodes-base.webhook 통합 템플릿 보기 또는 모든 템플릿 검색

FAQ

외부 이벤트에서 워크플로를 어떻게 트리거하나요?

트리거로 웹훅 노드를 추가하세요. 이벤트가 발생할 때 앱·서비스에서 데이터를 받는 웹훅 URL을 만들고, 그 데이터로 워크플로를 시작합니다. 전용 앱 트리거 노드가 없는 서비스에 유용해요.

테스트 웹훅 URL과 프로덕션 웹훅 URL의 차이는 무엇인가요?

노드에는 웹훅 URL이 두 개 있어요. 테스트 URL은 테스트 이벤트 대기를 선택했을 때 동작하며 들어오는 데이터를 에디터에 표시합니다. 프로덕션 URL은 워크플로를 게시했을 때 등록되며 에디터에 데이터를 표시하지 않아요. 프로덕션 실행은 워크플로의 실행 탭에서 볼 수 있습니다.

웹훅을 어떻게 보호하나요?

지원되는 인증 방식에서 인증을 요구하면 됩니다. URL을 호출하는 모든 서비스에 Basic auth·Header auth·JWT auth를 사용할 수 있어요. IP 허용 목록 노드 옵션으로 호출자를 제한할 수도 있습니다. 자세한 내용은 웹훅 자격증명을 참고하세요.

흔한 문제

흔한 질문·이슈와 해결책은 흔한 문제(Common issues)를 참고하세요.