Webhook 노드를 사용하면 웹훅을 생성하여 이벤트가 발생할 때 앱과 서비스로부터 데이터를 수신할 수 있습니다. Webhook 노드는 트리거 노드로, n8n 워크플로우를 시작할 수 있습니다. 이를 통해 서비스가 n8n에 연결하여 워크플로우를 실행할 수 있습니다.

데이터를 수신하고 그 데이터를 기반으로 워크플로우를 실행하려는 경우 Webhook 노드를 워크플로우의 트리거로 사용할 수 있습니다. Webhook 노드는 워크플로우 끝에서 생성된 데이터를 반환하는 기능도 지원합니다. 이 덕분에 데이터를 처리하고 결과를 반환하는 워크플로우를 API 엔드포인트처럼 구축하는 데 유용합니다.

웹훅을 사용하면 전용 앱 트리거 노드가 없는 서비스에서도 워크플로우를 트리거할 수 있습니다.

워크플로우 개발 과정#

n8n은 테스트와 프로덕션을 위한 서로 다른 Webhook URL을 제공합니다. 테스트 URL에는 Listen for test event 옵션이 포함되어 있습니다. Webhook 노드를 빌드, 테스트하고 프로덕션으로 전환하는 방법에 대한 자세한 내용은 워크플로우 개발을 참고하세요.

노드 매개변수#

이 매개변수를 사용하여 노드를 구성합니다.

Webhook URLs#

Webhook 노드에는 테스트용과 프로덕션용 두 개의 Webhook URL이 있습니다. n8n은 노드 패널 상단에 이 URL을 표시합니다.

Test URL 또는 Production URL을 선택하여 n8n이 표시하는 URL을 전환합니다.

• Test: 워크플로우가 활성화되어 있지 않은 경우, Listen for Test Event 또는 Execute workflow를 선택하면 n8n이 테스트 웹훅을 등록합니다. 웹훅 URL을 호출하면 n8n이 워크플로우에 데이터를 표시합니다.
• Production: 워크플로우를 게시하면 n8n이 프로덕션 웹훅을 등록합니다. 프로덕션 URL을 사용하는 경우 n8n은 워크플로우에 데이터를 표시하지 않습니다. 프로덕션 실행의 워크플로우 데이터는 여전히 확인할 수 있습니다. 워크플로우에서 Executions 탭을 선택한 다음 확인하려는 워크플로우 실행을 선택하세요.

HTTP 메서드#

Webhook 노드는 표준 HTTP 요청 메서드를 지원합니다:

• DELETE

• GET

• HEAD

• PATCH

• POST

• PUT
  

  웹훅 최대 페이로드

  웹훅의 최대 페이로드 크기는 16MB입니다. n8n을 셀프 호스팅하는 경우 엔드포인트 환경 변수 N8N_PAYLOAD_SIZE_MAX를 사용하여 이 값을 변경할 수 있습니다.

경로#

기본적으로 이 필드에는 다른 webhook 노드와의 충돌을 피하기 위해 무작위로 생성된 웹훅 URL 경로가 들어 있습니다.

경로 매개변수 추가를 포함하여 URL 경로를 직접 지정할 수 있습니다. 예를 들어 n8n으로 API를 프로토타이핑하면서 일관된 엔드포인트 URL을 원하는 경우 이 작업이 필요할 수 있습니다.

Path 필드는 다음 형식을 사용할 수 있습니다:

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

지원되는 인증 방식#

웹훅 URL을 호출하는 모든 서비스에 대해 인증을 요구할 수 있습니다. 다음 인증 방식 중에서 선택하세요:

• Basic auth
• Header auth
• JWT auth
• None

각 자격 증명 유형을 설정하는 방법에 대한 자세한 내용은 Webhook 자격 증명을 참고하세요.

응답#

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

응답 코드#

Webhook 노드가 성공적으로 실행된 후 반환하는 HTTP 응답 코드를 사용자 지정합니다. 일반적인 응답 코드 중에서 선택하거나 사용자 지정 코드를 만들 수 있습니다.

응답 데이터#

응답 본문에 포함할 데이터를 선택합니다:

• All Entries: Webhook이 마지막 노드의 모든 항목을 배열로 반환합니다.
• First Entry JSON: Webhook이 마지막 노드의 첫 번째 항목에 대한 JSON 데이터를 JSON 객체로 반환합니다.
• First Entry Binary: Webhook이 마지막 노드의 첫 번째 항목에 대한 바이너리 데이터를 바이너리 파일로 반환합니다.
• No Response Body: Webhook이 본문 없이 반환합니다.

Respond > When Last Node Finishes에만 적용됩니다.

노드 옵션#

Add Option을 선택하면 더 많은 구성 옵션을 볼 수 있습니다. 사용 가능한 옵션은 노드 매개변수에 따라 달라집니다. 옵션 사용 가능 여부는 표를 참고하세요.

• Allowed Origins (CORS): 허용되는 교차 출처 도메인을 설정합니다. 교차 출처 비프리플라이트(non-preflight) 요청에 허용되는 URL을 쉼표로 구분한 목록으로 입력합니다. 모든 출처를 허용하려면 *(기본값)을 사용하세요.
• Binary Property: 이 설정을 활성화하면 Webhook 노드가 이미지나 오디오 파일 같은 바이너리 데이터를 수신할 수 있습니다. 수신한 파일의 데이터를 기록할 바이너리 속성의 이름을 입력합니다.
• Ignore Bots: 링크 미리보기 도구나 웹 크롤러 같은 봇의 요청을 무시합니다.
• IP(s) Whitelist: Webhook 트리거 URL을 호출할 수 있는 대상(또는 주체)을 제한하려면 이 옵션을 활성화합니다. 허용되는 IP 주소를 쉼표로 구분한 목록으로 입력합니다. 화이트리스트에 없는 IP 주소에서의 접근은 403 오류를 발생시킵니다. 비워 두면 모든 IP 주소가 웹훅 트리거 URL을 호출할 수 있습니다.
• No Response Body: n8n이 응답과 함께 본문을 보내지 않도록 하려면 이 옵션을 활성화합니다.
• Raw Body: Webhook 노드가 JSON이나 XML 같은 원시(raw) 형식으로 데이터를 수신하도록 지정합니다.
• Response Content-Type: 웹훅 본문의 형식을 선택합니다.
• Response Data: 응답과 함께 사용자 지정 데이터를 보냅니다.
• Response Headers: Webhook 응답에 추가 헤더를 보냅니다. 응답 헤더에 대한 자세한 내용은 MDN Web Docs | Response header를 참고하세요.
• Property Name: 기본적으로 n8n은 사용 가능한 모든 데이터를 반환합니다. 특정 JSON 키를 반환하도록 선택하면 n8n이 해당 값을 반환합니다.

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

n8n 버전 1.103.0부터 n8n은 웹훅에 대한 HTML 응답을 자동으로 <iframe> 태그로 감쌉니다. 이는 인스턴스 사용자를 보호하기 위한 보안 메커니즘입니다.

이로 인해 다음과 같은 영향이 있습니다:

• HTML이 상위 문서에 직접 렌더링되지 않고 샌드박스 처리된 iframe 안에서 렌더링됩니다.
• 최상위 창이나 로컬 스토리지에 접근하려는 JavaScript 코드는 실패합니다.
• 인증 헤더(예: basic auth)는 샌드박스 처리된 iframe에서 사용할 수 없습니다. HTML 내에 수명이 짧은 액세스 토큰을 삽입하는 등의 대체 방식을 사용해야 합니다.
• 상대 URL(예: <form action="/">)은 작동하지 않습니다. 대신 절대 URL을 사용하세요.

템플릿 및 예시#

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

FAQ#

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

Webhook 노드를 트리거로 추가하세요. 이 노드는 이벤트가 발생할 때 앱과 서비스로부터 데이터를 수신하는 웹훅 URL을 생성한 다음, 해당 데이터로 워크플로우를 시작합니다. 전용 앱 트리거 노드가 없는 서비스에 유용합니다.

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

이 노드에는 두 개의 웹훅 URL이 있습니다. 테스트(test) URL은 Listen for Test Event를 선택하면 작동하며, 에디터에 수신 데이터를 표시합니다. 프로덕션(production) URL은 워크플로우를 게시하면 등록되며, 에디터에 데이터를 표시하지 않습니다. 프로덕션 실행 내역은 워크플로우의 Executions 탭에서 확인할 수 있습니다.

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

지원되는 인증 방식에서 인증을 요구하세요. URL을 호출하는 모든 서비스에 대해 Basic auth, Header auth, JWT auth를 사용할 수 있습니다. 또한 IP(s) Whitelist 노드 옵션으로 호출자를 제한할 수도 있습니다. Webhook 자격 증명을 참고하세요.

일반적인 문제#

일반적인 질문이나 문제 및 권장 해결 방법은 일반적인 문제를 참고하세요.