[n8n] Webhook에서 Path Param 사용하기

1️⃣ [n8n] Webhook에서 Path Param 사용하기

1. 기본 URL 구조

n8n에서 Webhook 노드를 생성하면 URL은 항상 이렇게 만들어집니다.

 

{BASE_URL}/webhook(-test)/{webhookId}/{path}

• /webhook vs /webhook-test
  • /webhook-test: 에디터에서 테스트 실행할 때
  • /webhook: 실제 프로덕션 실행
• {webhookId}
  • Webhook 노드가 생성될 때 자동으로 부여되는 고유 식별자
  • 예: 82dbbc6d-bd6b-401a-935d-49b08bc84d75
• {path}
  • 사용자가 지정하는 경로
  • Path Param(:filename)도 여기에 포함 가능

---

2. Path Param 사용 예시

Webhook 노드에서 이렇게 설정했다고 가정해봅시다.

 

"path": "n8n/manuals/delete/:filename"

그럼 최종 URL은 다음과 같이 생성됩니다.

 

https://dev.example.com:10300/webhook-test/12abcd-abcd-12ab-123a-12345678/n8n/manuals/delete/myFile.pdf

그리고 n8n 내부에서 파라미터는 이렇게 꺼낼 수 있습니다.

{{$json["params"]["filename"]}}

→ "myFile.pdf"

---

3. 왜 webhookId가 꼭 들어갈까?

• n8n은 하나의 워크플로우 안에 Webhook 노드를 여러 개 둘 수 있습니다.
• 단순히 path만 가지고는 어떤 노드를 호출해야 할지 구분할 수 없습니다.
• 그래서 n8n은 webhookId + path 조합으로 엔드포인트를 유일하게 만듭니다.

즉, Path Param을 쓰든 안 쓰든 webhookId는 무조건 포함돼야 해요.
82dbbc6d-bd6b-401a-935d-49b08bc84d75 같은 값이 바로 그 역할을 합니다.

---

4. 깔끔한 API 주소 만들기

문제는 이 webhookId가 외부 API 문서에 그대로 노출되면 주소가 지저분하다는 점입니다.

👉 해결책은 **리버스 프록시(Nginx 등)**를 두고 webhookId를 감추는 것.

예를 들어:

location /chatbot/n8n/manuals/delete/ {
    proxy_pass http://127.0.0.1:10300/webhook/12abcd-abcd-12ab-123a-12345678/n8n/manuals/delete/;
}

 

외부 호출:

https://dev.example.com/chatbot/n8n/manuals/delete/myFile.pdf

 

내부 매핑:

 

http://127.0.0.1:10300/webhook/12abcd-abcd-12ab-123a-12345678/n8n/manuals/delete/myFile.pdf

---

5. 정리

• n8n Webhook은 webhookId가 반드시 포함된 경로를 생성한다.
• Path Param(:filename)을 쓰려면 이 구조에 따라야 한다.
• webhookId는 여러 Webhook 노드를 구분하기 위한 고유 식별자다.
• 외부 API를 깔끔하게 제공하려면 프록시(Nginx 등)로 webhookId를 숨기자.

---

👉 요약하면, n8n에서 Path Param을 쓰려면 webhookId가 붙는 건 선택이 아니라 필수입니다.
API를 외부에 제공할 때는 프록시로 감추는 게 정석이에요.

 

 

 

 

2️⃣ 리버스 프록시(Nginx)를 쓰면 외부에서 webhookId가 안 보이게 감추는 방법

리버스 프록시(Nginx)를 쓰면 외부에서 webhookId가 안 보이게 감출 수 있습니다. 핵심은 외부 URL → 내부 실제 n8n URL로 매핑해 주는 거예요.

1. 구조 이해

n8n이 제공하는 실제 URL:

https://dev.example.com:10300/webhook/12abcd-abcd-12ab-123a-12345678/n8n/manuals/delete/:filename

 

외부에 공개하고 싶은 URL:

https://api.example.com/chatbot/n8n/manuals/delete/:filename

 

 

2. Nginx 설정 예시

/etc/nginx/conf.d/api.conf 같은 곳에 아래처럼 추가합니다.

server {
    listen 443 ssl;
    server_name api.example.com;

    # SSL 인증서
    ssl_certificate     /etc/letsencrypt/live/api.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/api.example.com/privkey.pem;

    location /chatbot/n8n/manuals/delete/ {
        proxy_pass http://127.0.0.1:10300/webhook/12abcd-abcd-12ab-123a-12345678/n8n/manuals/delete/;

        # 헤더/보안 옵션
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

 

 

3. 동작 방식

• 클라이언트는 깔끔한 주소로 요청

https://api.example.com/chatbot/n8n/manuals/delete/myFile.pdf

 

• Nginx가 내부적으로 webhookId가 포함된 n8n 주소로 포워딩:

http://127.0.0.1:10300/webhook/12abcd-abcd-12ab-123a-12345678/n8n/manuals/delete/myFile.pdf

• 클라이언트는 webhookId를 몰라도 호출 가능.

 

4. 확장 패턴

다른 API들도 같은 방식으로 감출 수 있습니다.
예를 들어 /chatbot/n8n/user/chat → 내부 …/webhook/{webhookId}/n8n/user/chat 매핑.

---

✅ 요약:

• n8n은 webhookId를 무조건 붙여야 동작함.
• 하지만 외부 API는 프록시(Nginx)로 path rewriting 해주면 webhookId 감출 수 있음.
• location /외부경로/ { proxy_pass http://내부:포트/실제경로/; } 구조로 쓰면 된다.

 

 

 

 

 

참고 링크

https://community.n8n.io/t/webhook-path-parameters-hash/14913

Webhook path parameters hash