적용 범위: 이 글은 Cloudflare Quick Tunnel로 연결한 자체 호스팅(self-hosted) n8n의 Telegram Webhook 방식을 대상으로 합니다. 고정 도메인+리버스 프록시, ngrok, n8n Cloud 등 다른 연결 방식에는 세부 확인 지점이 다르게 적용될 수 있습니다.
Telegram 봇에 말을 걸었는데 n8n 워크플로가 반응하지 않을 때, 어디서 막혔는지 모르면 할 수 있는 게 “일단 재시작”뿐입니다. 재시작으로 해결되는 경우도 있지만, 왜 해결됐는지 모르면 같은 문제가 또 생깁니다.
이 글은 그 “어디서 막혔는가”를 구분하는 순서를 다룹니다. Telegram → 공개 접속 주소 → n8n → 워크플로 실행, 네 지점을 순서대로 좁혀가는 진단표입니다.
실제로 저희가 겪은 장애 하나는 이미 n8n 자동화 구축 전 확인할 12가지 — 발주자 체크리스트에서 다뤘습니다. 이 글은 그 사례를 다시 설명하지 않고, 그 사례가 남긴 질문(“재시작 후에도 같은 문제가 재발하지 않는지 어떻게 확인하는가”)을 포함해 반복해서 쓸 수 있는 진단 순서로 정리했습니다.
먼저 확인하세요: 아래 진단 과정에서 Telegram 토큰, API 키, 계정 정보가 담긴 화면은 어디에도 붙여넣거나 캡처해 공유하지 마세요. 진단에는 토큰 값 자체가 아니라 그 응답의 구조만 있으면 충분합니다.
진단 전에 알아둘 것
- 이 진단표는 4개 지점을 순서대로 확인합니다. 앞 단계에서 이상이 없으면 다음 단계로 넘어가고, 이상이 발견되면 거기서 멈춰 그 지점을 먼저 조치합니다.
- 오류 코드 하나만으로 원인을 확정하지 않습니다. 예를 들어 HTTP 530은 Cloudflare가 오리진 호스트명을 확인하지 못했다는 뜻이지만, 그 호스트명이 왜 확인되지 않았는지는 다음 단계를 봐야 압니다.
- 이 글은 Telegram, Cloudflare, n8n 공식 문서를 바탕으로 정리한 진단 안내입니다. 저희가 실제로 겪은 사례 하나(위 링크)를 참고했지만, 아래 모든 단계를 매번 실제 환경에서 다시 시험해 검증한 것은 아닙니다.
- 아래 “확인 방법”은 전부 사용자가 본인 환경에서 직접 실행하는 절차입니다.
1단계 — Telegram이 실제로 전달을 시도하고 있는가
| 확인 항목 | 확인 방법 | 관찰 결과의 의미 | 다음 조치 |
|---|---|---|---|
| 웹훅이 등록돼 있는가 | 브라우저나 터미널에서 https://api.telegram.org/bot<내 토큰>/getWebhookInfo를 직접 호출해 응답을 본다(Telegram Bot API) | url 필드가 비어 있으면 웹훅 자체가 등록되지 않은 상태다(getUpdates 방식으로 바뀌어 있을 수 있다) | 비어 있으면 webhook 재등록이 먼저다. 비어 있지 않으면 다음 행으로 |
| 전달이 밀려 있는가 | 같은 응답의 pending_update_count 값을 본다 | 0보다 크면 전달을 기다리는 업데이트가 있다는 뜻이다. 이 값이 지속적으로 증가하는 것과 last_error_date/last_error_message에 최근 시각의 오류가 함께 있는 경우에 전달 문제를 의심할 근거가 된다 — 이 값 하나만으로 전달 실패를 단정하지 않는다 | 의심 근거가 함께 있으면 2단계로 이동 |
| 가장 최근 오류가 언제·무엇이었는가 | 같은 응답의 last_error_date(발생 시각)와 last_error_message(오류 내용)를 본다 | 이 값은 “가장 최근에 발생한 오류”의 기록이며 지금 이 순간의 상태를 보장하지 않는다. 시각이 오래전이면 이미 해결된 문제일 수 있다 | last_error_date가 방금이면 지금도 문제가 진행 중일 가능성이 높다. 2단계로 |
Telegram은 전달 실패 시 “합리적인 횟수”만큼 재시도하고, 받지 못한 업데이트는 최대 24시간까지만 서버에 보관합니다.
2단계 — 등록된 주소와 지금 쓰는 공개 주소가 같은가
getWebhookInfo의 url 값에는 호스트명뿐 아니라 n8n이 실제로 쓰는 웹훅 경로까지 전체가 포함됩니다. 단순히 도메인만 비교하면 안 됩니다.
| 확인 항목 | 확인 방법 | 관찰 결과의 의미 | 다음 조치 |
|---|---|---|---|
| 호스트명 일치 여부 | 1단계에서 본 url의 https:// 다음 호스트명 부분과, 지금 cloudflared 실행 중 터미널에 출력된 trycloudflare.com 주소의 호스트명 부분을 비교한다 | Cloudflare 공식 문서는 Quick Tunnel의 호스트명이 터널을 새로 만들 때마다 바뀐다고 설명한다. 호스트명이 다르면, 재시작 이후 이전 주소가 그대로 등록돼 남아 있는 상태일 가능성이 크다 | 다르면 아래 “경로 일치 여부”까지 함께 확인한다 |
| 경로 일치 여부 | url의 전체 경로를, n8n 편집기에서 해당 Telegram Trigger 노드가 표시하는 예상 Webhook URL(전체 경로 포함)과 비교한다 | 호스트명은 같은데 경로가 다르면 터널 문제가 아니라 다른 원인(Trigger 노드 재설정, 같은 봇에 연결된 다른 워크플로 존재 등)일 수 있다 — 호스트명 불일치와 같은 원인으로 보지 않는다 | 경로까지 다르면 그 사실만 기록한다. 터널의 기본 주소만으로 setWebhook을 수동 등록하지 않는다 — 올바른 전체 주소는 n8n Telegram Trigger 노드 화면에서 직접 확인해야 하며, 실제 재등록은 운영 설정 변경이라 이 글의 범위 밖이다 |
| cloudflared 프로세스가 떠 있는가 | 터널을 실행한 터미널이나 프로세스 목록에서 cloudflared가 지금 살아 있는지 확인한다 | Cloudflare 공식 문서: “The URL stops working when you stop the cloudflared process.” 프로세스가 죽어 있으면 1단계 오류의 원인 중 하나로 설명된다 | 꺼져 있으면 재시작한다 — 재시작하면 주소가 새로 발급되므로 반드시 위 호스트명·경로 일치 확인을 다시 거친다 |
| 공개 주소가 응답하는가 | 그 trycloudflare.com 주소를 브라우저로 열어보면서, (a) 연결 자체가 안 되는지, (b) Cloudflare가 돌려주는 오류 페이지(오류 코드 포함)인지, (c) 로컬 n8n이 실제로 응답하는 내용인지를 구분해서 본다 | 공개 주소가 응답하지 않는다는 사실 하나만으로 터널 장애를 확정하지 않는다. cloudflared가 떠 있는데도 응답이 없다면 터널이 아니라 로컬 n8n이나 네트워크 쪽 문제일 수 있다. Cloudflare의 오류 530은 “오리진 호스트명을 확인(해석)하지 못했다”는 뜻이며, 이 코드가 보이면 함께 기록한다 | (a)라면 터널 쪽으로 좁혀진다. (b)라면 오류 코드를 기록하고 3단계로. (c)라면 공개 주소 자체는 살아 있으므로 3단계로 |
Quick Tunnel은 “가동률 보장이 없다”고 공식 문서가 명시하는 테스트·개발용 연결 방식입니다. 운영 중인 봇이 자주 이 지점에서 끊긴다면, 이 진단표로 매번 복구하는 것과 더 안정적인 연결 방식으로 바꾸는 것 중 어느 쪽이 맞는지는 이 글의 범위를 넘는 별도 판단입니다.
3단계 — n8n이 요청을 실제로 받고 있는가
| 확인 항목 | 확인 방법 | 관찰 결과의 의미 | 다음 조치 |
|---|---|---|---|
| n8n에 등록된 웹훅 주소가 최신인가 | 설치된 n8n 버전에 맞는 공식 문서에서 WEBHOOK_URL(구버전 명칭) 또는 N8N_WEBHOOK_URL(현재 명칭) 환경변수 설명을 확인하고, 그 값을 조회한다 | 공식 문서는 이 값이 “편집기에 표시되는 웹훅 주소”와 “외부 서비스에 등록하는 주소”를 결정한다고 설명한다. 오래된 값이 남아 있을 때 정확히 어떤 오류가 발생하는지는 문서에 구체적으로 나와 있지 않다 — 값이 낡았다면 외부 서비스가 더 이상 유효하지 않은 주소로 계속 요청을 보내게 될 수 있다는 점만 참고로 둔다 | 값이 2단계에서 확인한 현재 주소와 다르면 그 사실만 기록한다. 버전을 업그레이드하거나 설정을 직접 바꾸지 않고, 설치된 버전에 맞는 공식 문서를 먼저 확인한다 |
| 저장·필터·활성화 상태를 먼저 확인했는가 | n8n Executions(실행 기록) 화면을 열기 전에 다음 네 가지를 먼저 확인한다: ① 워크플로 설정의 “Save successful/failed production executions”가 저장하지 않음으로 돼 있는지, ② 지금 걸려 있는 조회 필터(Status/시간 범위/워크플로 선택), ③ 해당 워크플로가 Active(활성화) 상태인지, ④ 이 워크플로가 쓰는 Webhook이 Test URL인지 Production URL인지(n8n 공식 문서) | 이 네 가지 중 하나라도 조회를 가리고 있다면, 실행 기록이 안 보인다는 사실이 “요청이 안 왔다”를 의미하지 않을 수 있다 | 네 가지를 먼저 점검한다 |
| 해당 시간대 실행이 있는가 | 위 네 가지를 확인한 뒤, 그 시간대 실행이 있는지 Executions 목록에서 본다. 공식 문서에 나온 Status 필터는 Failed/Running/Success/Waiting이다 | 네 가지를 모두 확인한 뒤에도 실행이 전혀 없다면, 요청이 앞단(2단계: 터널·webhook 등록)에서 막혔을 가능성이 커진다. 실행이 있는데 Failed라면 요청은 도달했고 문제는 워크플로 내부다 | 실행이 없으면(네 가지 점검 후에도) 2단계로 돌아간다. 실행이 있는데 실패라면 4단계로 |
4단계 — 도달한 요청이 워크플로 안에서 실패하거나 조용히 멈추는 경우
| 확인 항목 | 확인 방법 | 관찰 결과의 의미 | 다음 조치 |
|---|---|---|---|
| 어느 노드에서 멈췄는가 | 해당 Execution을 열어 실패로 표시된 노드를 확인한다 | 특정 노드에서 멈췄다면 그 노드가 연동하는 서비스 쪽(인증 방식 변경, 응답 형식 변경 등) 문제일 가능성이 있다. 오류 메시지 하나만으로 원인을 확정하지 않는다 — 그 서비스의 공식 문서나 상태 페이지로 대조해야 한다 | 노드별 오류 메시지를 그 연동 서비스의 공식 문서와 대조한다 |
| 실행이 Success인데도 답장이 없다면 | 그 Execution을 열어 Telegram 전송(응답) 노드가 실제로 실행됐는지, 그 노드의 출력 결과가 무엇인지 확인한다. 워크플로에 분기(IF/Switch) 노드가 있다면 그 분기를 통과했는지도 함께 본다 | 전체 실행이 Success로 표시돼도, 특정 노드가 “오류 무시(Continue on Fail / On Error: Continue)”로 설정돼 있으면 그 노드가 실패했는데도 전체 실행은 성공으로 표시될 수 있다. 분기 조건 때문에 Telegram 전송 노드 자체가 실행되지 않았을 수도 있다 | 전송 노드가 실행되지 않았거나 실패했다면, 그 노드의 조건·오류 설정을 확인한다(설정 변경은 이 글 범위 밖, 확인만) |
| 재발을 시스템이 감지할 수 있는가 | 워크플로 설정에서 에러 워크플로(Error Trigger로 시작하는 별도 워크플로)가 지정돼 있는지 확인한다(n8n 공식 문서) | 지정돼 있지 않다면, 이 특정 안전장치는 없는 상태라는 것만 확인된다 — 다른 방식의 모니터링(외부 헬스체크 등)을 따로 쓰고 있는지는 이 확인만으로 알 수 없다 | 지정 여부만 확인·기록한다. 이번 글에서 직접 추가하지는 않는다(운영 설정 변경은 범위 밖) |
| 복구 후 유실·중복 여부 | 복구 후 1단계의 pending_update_count를 다시 확인하고, 그 전후로 실제 메시지가 왔는지 사람이 대조한다 | pending_update_count가 0이라는 사실만으로 유실이나 중복이 없다고 판정하지 않는다 — 이 값은 “대기 중” 개수일 뿐, 중복 수신 여부는 메시지 ID를 따로 대조해야 확인된다. setWebhook의 drop_pending_updates는 미전달 업데이트를 버리는 옵션이며, 복구가 됐는지를 확인해주는 방법이 아니다 | 유실·중복을 확인하려면 메시지 ID 기준으로 직접 대조한다 |
이 진단표로 확정할 수 없는 것
- 1차 원인의 “왜”: 이 표는 어느 지점이 막혔는가를 좁히는 순서이지, 그 지점이 왜 막혔는지(예: cloudflared가 왜 멈췄는지)까지 자동으로 설명해주지 않습니다. 각 지점의 로그와 공식 문서를 추가로 봐야 합니다.
- 재발 방지 여부: 문제 지점을 찾아 조치했더라도, 그 조치가 다음 재시작·다음 장애에도 유효한지는 이 표만으로 확인되지 않습니다. 특히 주소가 매번 바뀌는 Quick Tunnel 방식에서는 같은 점검을 반복해야 합니다.
참고한 자료
- Telegram, Bot API — getWebhookInfo / setWebhook / Getting updates
- Cloudflare 공식 문서, Quick Tunnels (TryCloudflare)
- Cloudflare 공식 문서, Error 530
- n8n 공식 문서, Configure webhook URLs (reverse proxy / N8N_WEBHOOK_URL) — 설치된 버전과 문서 버전이 다를 수 있으니 본인 버전에 맞는 문서를 확인하세요.
- n8n 공식 문서, Executions 개요
- n8n 공식 문서, View all executions
- n8n 공식 문서, Handle errors gracefully
이 글의 진단표는 일잘랩이 자체적으로 정리한 점검 순서이며 업계 표준이 아닙니다. 공식 문서를 바탕으로 작성했으나, 모든 단계를 실제 환경에서 매번 시험해 검증한 것은 아닙니다. 특정 장애의 원인을 보장하거나 복구를 약속하지 않습니다.
기준 시점 2026년 10월 25일