InfoGrab DocsInfoGrab Docs

Webhook 노드 문서

요약

Webhook 노드를 사용하면 웹훅을 생성하여 이벤트가 발생할 때 앱과 서비스로부터 데이터를 수신할 수 있습니다. 데이터를 수신하고 그 데이터를 기반으로 워크플로를 실행하려는 경우 Webhook 노드를 워크플로의 트리거로 사용할 수 있습니다.

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을 전환합니다.

Webhook 노드의 Parameters 탭에 표시된 Webhook 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
  • n8n User Auth (OAuth2)
  • None

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

n8n User Auth (OAuth2) 사용#

이 n8n 인스턴스에 로그인한 사용자만 웹훅을 호출할 수 있습니다. 호출자는 이 인스턴스가 발급한 OAuth2 베어러 토큰을 전송해야 합니다. n8n은 토큰을 호출한 사용자로 확인하고 해당 사용자로 실행을 수행합니다. 이 모드에서 최종 사용자 자격 증명은 호출한 사용자가 연결한 계정으로 확인됩니다.

베어러 토큰이 없는 요청은 다음과 같이 처리됩니다.

  • 브라우저의 GET 요청은 n8n 로그인 페이지로 리디렉션됩니다. 사용자가 로그인하고 동의하면 n8n이 브라우저를 웹훅 URL로 다시 리디렉션하고 워크플로를 실행합니다.
  • 그 밖의 모든 요청은 401 응답을 받습니다. GET 요청만 리디렉션할 수 있습니다.

노드 옵션의 OAuth2 Client 옵션이 이 동작을 제어합니다.

**n8n User Auth (OAuth2)**를 선택하면 Require Workflow Execute Permission 토글이 나타납니다. 기본적으로 켜져 있습니다. 켜져 있으면 호출한 사용자가 워크플로가 속한 프로젝트에서 해당 워크플로를 실행할 권한도 있어야 합니다. 로그인했지만 워크플로에 대한 실행 권한이 없는 사용자는 워크플로를 트리거할 수 없습니다. 이러한 사용자가 베어러 토큰과 함께 보낸 요청은 403 응답을 받습니다.

n8n User Auth (OAuth2)를 사용하는 웹훅 호출#

n8n은 웹훅의 OAuth2 인가 서버입니다. 호출자가 베어러 토큰을 얻는 방법은 호출자에 따라 다릅니다.

  • 브라우저: 웹훅 URL을 엽니다. n8n이 로그인 페이지와 동의 화면으로 리디렉션한 다음 워크플로를 실행합니다. 이 방법은 GET 요청에서만 작동하며, OAuth2 Client가 Auto-Detect 또는 **Browser (Virtual Client)**일 때만 사용할 수 있습니다.
  • OAuth 2.1 디스커버리를 지원하는 클라이언트: OAuth2 Client를 Bearer Token Only로 설정하거나, 브라우저가 아닌 요청에는 Auto-Detect를 사용한 다음 토큰 없이 요청을 보냅니다. 401 응답에는 resource_metadata URL이 포함된 WWW-Authenticate 헤더가 들어 있습니다. 보호된 리소스 메타데이터, 동적 클라이언트 등록, PKCE를 지원하는 클라이언트는 이 URL을 사용해 수동 설정 없이 로그인과 동의를 완료합니다.
  • 직접 만든 스크립트 또는 서비스: n8n 인스턴스에 대해 OAuth2 인가 코드 플로를 완료합니다.
    1. https://<your-n8n-url>/.well-known/oauth-authorization-server에서 인가 서버 메타데이터를 읽습니다. 여기에 등록, 인가, 토큰 엔드포인트가 나열되어 있습니다.
    2. 등록 엔드포인트에서 클라이언트를 등록하거나, 이전에 등록한 클라이언트를 재사용합니다.
    3. PKCE(S256)와 함께 사용자를 인가 엔드포인트로 보냅니다. 이때 resource 파라미터는 웹훅 URL에 ?method=를 붙인 값으로 설정합니다. 예: https://<your-n8n-url>/webhook/my-path?method=POST. 사용자가 로그인하고 동의합니다.
    4. 토큰 엔드포인트에서 인가 코드를 액세스 토큰과 리프레시 토큰으로 교환합니다.
    5. Authorization: Bearer <access token> 헤더와 함께 웹훅을 호출합니다.

토큰은 발급받은 웹훅 트리거에 바인딩됩니다. 다른 트리거나 인스턴스의 MCP 서버용으로 발급된 토큰은 401 응답을 받습니다.

응답#

  • 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) Allowlist: Webhook 트리거 URL을 호출할 수 있는 대상(또는 주체)을 제한하려면 이 옵션을 활성화합니다. 허용되는 IP 주소를 쉼표로 구분한 목록으로 입력합니다. 허용 목록에 없는 IP 주소에서의 접근은 403 오류를 발생시킵니다. 비워 두면 모든 IP 주소가 웹훅 트리거 URL을 호출할 수 있습니다.
  • No Response Body: n8n이 응답과 함께 본문을 보내지 않도록 하려면 이 옵션을 활성화합니다.
  • OAuth2 Client: Authentication이 **n8n User Auth (OAuth2)**일 때 n8n이 베어러 토큰이 없는 요청을 처리하는 방식입니다. Auto-Detect(기본값)는 브라우저 탐색을 n8n 로그인 페이지로 리디렉션하고 그 외 모든 요청에는 베어러 토큰을 요구합니다. Bearer Token Only는 항상 베어러 토큰을 요구하며 리디렉션하지 않습니다. **Browser (Virtual Client)**는 베어러 토큰이 없는 GET 요청을 항상 n8n 로그인 페이지로 리디렉션합니다. GET 요청만 리디렉션할 수 있습니다. 버전이 2.2 미만인 Webhook 노드는 이 옵션을 설정하기 전까지 Bearer Token Only 동작을 유지합니다.
  • Only Run If: 수신 요청에 대해 평가되는 표현식입니다. 표현식이 true를 반환할 때만 워크플로가 실행됩니다. $json을 사용하면 요청을 { body, headers, params, query } 형태로 참조할 수 있습니다. 예: {{ $json.body.campaign_id === 'user-research-invite' }}. 조건에 맞지 않는 요청에는 실행을 생성하지 않고 200 응답을 반환합니다. 표현식 평가에 실패하면 n8n은 경고를 기록하고 요청을 차단하지 않고 통과시킵니다. 이 검사는 IP 허용 목록과 인증 검사 이후에 실행되며, 테스트 웹훅 URL과 프로덕션 웹훅 URL 모두에 적용됩니다.
  • Raw Body: Webhook 노드가 JSON이나 XML 같은 원시(raw) 형식으로 데이터를 수신하도록 지정합니다.
  • Response Content-Type: 웹훅 본문의 형식을 선택합니다.
  • Response Data: 응답과 함께 사용자 지정 데이터를 보냅니다.
  • Response Headers: Webhook 응답에 추가 헤더를 보냅니다. 응답 헤더에 대한 자세한 내용은 MDN Web Docs | Response header를 참고하세요.
  • Property Name: 기본적으로 n8n은 사용 가능한 모든 데이터를 반환합니다. 특정 JSON 키를 반환하도록 선택하면 n8n이 해당 값을 반환합니다.
옵션 필요한 노드 구성
Allowed Origins (CORS) 모두
Binary Property

다음 중 하나:
HTTP Method > POST
HTTP Method > PATCH
HTTP Method > PUT

Ignore Bots 모두
IP(s) Allowlist 모두
Only Run If 모두
Property Name

둘 다:
Respond > When Last Node Finishes
Response Data > First Entry JSON

No Response Body Respond > Immediately
OAuth2 Client Authentication > n8n User Auth (OAuth2)
Raw Body 모두
Response Code Respond > Using 'Respond to Webhook' Node를 제외한 모두
Response Content-Type

둘 다:
Respond > When Last Node Finishes
Response Data > First Entry JSON

Response Data Respond > Immediately
Response Headers 모두

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

Note

기능 제공 범위

웹훅에 대한 HTML 응답을 <iframe> 태그로 자동으로 감싸는 기능은 n8n 1.103.0에서 도입되었습니다.

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를 사용할 수 있으며, 이 n8n 인스턴스에 로그인한 사용자로 호출자를 제한하려면 n8n User Auth (OAuth2)를 사용할 수 있습니다. 또한 IP(s) Allowlist 노드 옵션으로 호출자를 제한할 수도 있습니다. Webhook 자격 증명을 참고하세요.

일반적인 문제#

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

Webhook 노드 문서

n8n v2.47
원문 보기

요약

Webhook 노드를 사용하면 웹훅을 생성하여 이벤트가 발생할 때 앱과 서비스로부터 데이터를 수신할 수 있습니다. 데이터를 수신하고 그 데이터를 기반으로 워크플로를 실행하려는 경우 Webhook 노드를 워크플로의 트리거로 사용할 수 있습니다.

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을 전환합니다.

Webhook 노드의 Parameters 탭에 표시된 Webhook 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
  • n8n User Auth (OAuth2)
  • None

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

n8n User Auth (OAuth2) 사용#

이 n8n 인스턴스에 로그인한 사용자만 웹훅을 호출할 수 있습니다. 호출자는 이 인스턴스가 발급한 OAuth2 베어러 토큰을 전송해야 합니다. n8n은 토큰을 호출한 사용자로 확인하고 해당 사용자로 실행을 수행합니다. 이 모드에서 최종 사용자 자격 증명은 호출한 사용자가 연결한 계정으로 확인됩니다.

베어러 토큰이 없는 요청은 다음과 같이 처리됩니다.

  • 브라우저의 GET 요청은 n8n 로그인 페이지로 리디렉션됩니다. 사용자가 로그인하고 동의하면 n8n이 브라우저를 웹훅 URL로 다시 리디렉션하고 워크플로를 실행합니다.
  • 그 밖의 모든 요청은 401 응답을 받습니다. GET 요청만 리디렉션할 수 있습니다.

노드 옵션의 OAuth2 Client 옵션이 이 동작을 제어합니다.

**n8n User Auth (OAuth2)**를 선택하면 Require Workflow Execute Permission 토글이 나타납니다. 기본적으로 켜져 있습니다. 켜져 있으면 호출한 사용자가 워크플로가 속한 프로젝트에서 해당 워크플로를 실행할 권한도 있어야 합니다. 로그인했지만 워크플로에 대한 실행 권한이 없는 사용자는 워크플로를 트리거할 수 없습니다. 이러한 사용자가 베어러 토큰과 함께 보낸 요청은 403 응답을 받습니다.

n8n User Auth (OAuth2)를 사용하는 웹훅 호출#

n8n은 웹훅의 OAuth2 인가 서버입니다. 호출자가 베어러 토큰을 얻는 방법은 호출자에 따라 다릅니다.

  • 브라우저: 웹훅 URL을 엽니다. n8n이 로그인 페이지와 동의 화면으로 리디렉션한 다음 워크플로를 실행합니다. 이 방법은 GET 요청에서만 작동하며, OAuth2 Client가 Auto-Detect 또는 **Browser (Virtual Client)**일 때만 사용할 수 있습니다.
  • OAuth 2.1 디스커버리를 지원하는 클라이언트: OAuth2 Client를 Bearer Token Only로 설정하거나, 브라우저가 아닌 요청에는 Auto-Detect를 사용한 다음 토큰 없이 요청을 보냅니다. 401 응답에는 resource_metadata URL이 포함된 WWW-Authenticate 헤더가 들어 있습니다. 보호된 리소스 메타데이터, 동적 클라이언트 등록, PKCE를 지원하는 클라이언트는 이 URL을 사용해 수동 설정 없이 로그인과 동의를 완료합니다.
  • 직접 만든 스크립트 또는 서비스: n8n 인스턴스에 대해 OAuth2 인가 코드 플로를 완료합니다.
    1. https://<your-n8n-url>/.well-known/oauth-authorization-server에서 인가 서버 메타데이터를 읽습니다. 여기에 등록, 인가, 토큰 엔드포인트가 나열되어 있습니다.
    2. 등록 엔드포인트에서 클라이언트를 등록하거나, 이전에 등록한 클라이언트를 재사용합니다.
    3. PKCE(S256)와 함께 사용자를 인가 엔드포인트로 보냅니다. 이때 resource 파라미터는 웹훅 URL에 ?method=를 붙인 값으로 설정합니다. 예: https://<your-n8n-url>/webhook/my-path?method=POST. 사용자가 로그인하고 동의합니다.
    4. 토큰 엔드포인트에서 인가 코드를 액세스 토큰과 리프레시 토큰으로 교환합니다.
    5. Authorization: Bearer <access token> 헤더와 함께 웹훅을 호출합니다.

토큰은 발급받은 웹훅 트리거에 바인딩됩니다. 다른 트리거나 인스턴스의 MCP 서버용으로 발급된 토큰은 401 응답을 받습니다.

응답#

  • 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) Allowlist: Webhook 트리거 URL을 호출할 수 있는 대상(또는 주체)을 제한하려면 이 옵션을 활성화합니다. 허용되는 IP 주소를 쉼표로 구분한 목록으로 입력합니다. 허용 목록에 없는 IP 주소에서의 접근은 403 오류를 발생시킵니다. 비워 두면 모든 IP 주소가 웹훅 트리거 URL을 호출할 수 있습니다.
  • No Response Body: n8n이 응답과 함께 본문을 보내지 않도록 하려면 이 옵션을 활성화합니다.
  • OAuth2 Client: Authentication이 **n8n User Auth (OAuth2)**일 때 n8n이 베어러 토큰이 없는 요청을 처리하는 방식입니다. Auto-Detect(기본값)는 브라우저 탐색을 n8n 로그인 페이지로 리디렉션하고 그 외 모든 요청에는 베어러 토큰을 요구합니다. Bearer Token Only는 항상 베어러 토큰을 요구하며 리디렉션하지 않습니다. **Browser (Virtual Client)**는 베어러 토큰이 없는 GET 요청을 항상 n8n 로그인 페이지로 리디렉션합니다. GET 요청만 리디렉션할 수 있습니다. 버전이 2.2 미만인 Webhook 노드는 이 옵션을 설정하기 전까지 Bearer Token Only 동작을 유지합니다.
  • Only Run If: 수신 요청에 대해 평가되는 표현식입니다. 표현식이 true를 반환할 때만 워크플로가 실행됩니다. $json을 사용하면 요청을 { body, headers, params, query } 형태로 참조할 수 있습니다. 예: {{ $json.body.campaign_id === 'user-research-invite' }}. 조건에 맞지 않는 요청에는 실행을 생성하지 않고 200 응답을 반환합니다. 표현식 평가에 실패하면 n8n은 경고를 기록하고 요청을 차단하지 않고 통과시킵니다. 이 검사는 IP 허용 목록과 인증 검사 이후에 실행되며, 테스트 웹훅 URL과 프로덕션 웹훅 URL 모두에 적용됩니다.
  • Raw Body: Webhook 노드가 JSON이나 XML 같은 원시(raw) 형식으로 데이터를 수신하도록 지정합니다.
  • Response Content-Type: 웹훅 본문의 형식을 선택합니다.
  • Response Data: 응답과 함께 사용자 지정 데이터를 보냅니다.
  • Response Headers: Webhook 응답에 추가 헤더를 보냅니다. 응답 헤더에 대한 자세한 내용은 MDN Web Docs | Response header를 참고하세요.
  • Property Name: 기본적으로 n8n은 사용 가능한 모든 데이터를 반환합니다. 특정 JSON 키를 반환하도록 선택하면 n8n이 해당 값을 반환합니다.
옵션 필요한 노드 구성
Allowed Origins (CORS) 모두
Binary Property

다음 중 하나:
HTTP Method > POST
HTTP Method > PATCH
HTTP Method > PUT

Ignore Bots 모두
IP(s) Allowlist 모두
Only Run If 모두
Property Name

둘 다:
Respond > When Last Node Finishes
Response Data > First Entry JSON

No Response Body Respond > Immediately
OAuth2 Client Authentication > n8n User Auth (OAuth2)
Raw Body 모두
Response Code Respond > Using 'Respond to Webhook' Node를 제외한 모두
Response Content-Type

둘 다:
Respond > When Last Node Finishes
Response Data > First Entry JSON

Response Data Respond > Immediately
Response Headers 모두

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

Note

기능 제공 범위

웹훅에 대한 HTML 응답을 <iframe> 태그로 자동으로 감싸는 기능은 n8n 1.103.0에서 도입되었습니다.

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를 사용할 수 있으며, 이 n8n 인스턴스에 로그인한 사용자로 호출자를 제한하려면 n8n User Auth (OAuth2)를 사용할 수 있습니다. 또한 IP(s) Allowlist 노드 옵션으로 호출자를 제한할 수도 있습니다. Webhook 자격 증명을 참고하세요.

일반적인 문제#

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