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

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

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

워크플로 개발 프로세스#

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

노드 파라미터#

이 파라미터를 사용하여 노드를 구성합니다.

Webhook URL#

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

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


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

HTTP Method#

Webhook 노드는 표준 HTTP Request Methods를 지원합니다:

• DELETE
• GET
• HEAD
• PATCH
• POST
• PUT

Path#

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

URL 경로를 수동으로 지정하고 경로 파라미터를 추가할 수 있습니다. 예를 들어 n8n을 사용하여 API를 프로토타입화하고 일관된 엔드포인트 URL이 필요한 경우 이 작업을 수행해야 할 수 있습니다.

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

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

지원되는 인증 방법#

웹훅 URL을 호출하는 모든 서비스에 인증을 요구할 수 있습니다. 다음 인증 방법 중 하나를 선택합니다:

• Basic auth
• Header auth
• JWT auth
• None

각 자격 증명 유형 설정에 대한 자세한 내용은 웹훅 자격 증명을 참조하세요.

Respond#

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

Response Code#

성공적인 실행 시 Webhook 노드가 반환하는 HTTP 응답 코드를 커스텀화합니다. 일반적인 응답 코드 중에서 선택하거나 커스텀 코드를 만들 수 있습니다.

Response Data#

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

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

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

노드 옵션#

Add Option을 선택하여 추가 구성 옵션을 확인합니다. 사용 가능한 옵션은 노드 파라미터에 따라 달라집니다. 옵션 사용 가능 여부는 표를 참조하세요.

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

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

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

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

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

템플릿 및 예시#

자주 발생하는 문제#

자주 묻는 질문이나 문제 및 해결 방법은 자주 발생하는 문제를 참조하세요.