텔레그램 봇 웹훅 확인 도구
클릭 한 번으로 텔레그램 봇의 웹훅을 확인하십시오. 도구가 getWebhookInfo를 호출해 URL, 대기 중인 업데이트, 마지막 전달 오류와 해결 힌트를 보여 주고, 웹훅을 설정하거나 삭제할 수 있게 해 줍니다.
토큰은 브라우저(localStorage)에만 저장되며 api.telegram.org로만 전송됩니다.
웹훅 설정 또는 변경
텔레그램 봇 웹훅 확인 방법
- 봇 토큰을 붙여넣으십시오. 봇이 테스트 환경에 있다면 테스트 서버에 체크하십시오.
- 웹훅 확인을 누르십시오. 결과는 세 가지 중 하나입니다: 웹훅 없음(봇이
getUpdates사용), 최근 24시간 동안 오류가 없는 웹훅, 또는 마지막 오류의 시각과 텍스트, 힌트가 포함된 전달 문제. - 대기 중인 업데이트 수를 확인하십시오. 100을 넘으면 강조 표시됩니다. 서버가 업데이트를 받지 않아 쌓이고 있다는 뜻입니다.
- 아래에
url,has_custom_certificate,pending_update_count,last_error_date,last_error_message,max_connections등getWebhookInfo응답 전체가 표시됩니다. - 변경하려면 웹훅 설정 또는 변경을 여십시오. HTTPS URL과 선택 사항인
secret_token을 입력하고, 대기 중인 업데이트를 버릴지 선택한 뒤 setWebhook 또는 deleteWebhook을 누르십시오. 확인이 자동으로 다시 실행됩니다.
자주 발생하는 웹훅 오류
힌트는 last_error_message의 텍스트에 따라 선택됩니다.
| 오류 형태 | 확인할 사항 |
|---|---|
| SSL / 인증서 | 도메인에 유효한 인증서(또는 setWebhook의 certificate 매개변수로 업로드한 자체 서명 인증서), TLS 1.2 이상. |
| Wrong response from the webhook: 4xx/5xx | 경로, secret_token 검사, 서버 오류. 텔레그램은 2xx를 기대합니다. |
| 타임아웃 / 연결 재설정 | 서버가 인터넷에서 443, 80, 88, 8443 포트 중 하나로 접근 가능하고 빠르게 응답해야 합니다. |
| 연결 거부 | 해당 포트에서 대기 중인 프로세스가 없거나 방화벽이 텔레그램을 차단하고 있습니다. |
| 호스트를 확인할 수 없음 | 웹훅 도메인의 DNS 레코드. |
양식은 url, secret_token, drop_pending_updates만 보냅니다. 시크릿(1–256자 A-Z a-z 0-9 _ -)은 모든 요청의 X-Telegram-Bot-Api-Secret-Token 헤더로 전달됩니다. allowed_updates, max_connections, 인증서는 /ko/telegram-bot-api-tester.html#setWebhook을 쓰십시오.
개인정보 보호
토큰은 브라우저의 localStorage에 저장되며, getWebhookInfo, setWebhook, deleteWebhook은 api.telegram.org로 바로 전송됩니다. 저희 서버를 거치는 것은 없습니다. 같은 호출은 /ko/telegram-bot-api-tester.html#getWebhookInfo에서도 할 수 있습니다. 전체 설정 과정은 /ko/guides/telegram-bot-webhook.html에, 409 Conflict 등 오류는 /ko/guides/telegram-bot-api-errors.html에서 다룹니다.
자주 묻는 질문
텔레그램 봇에 웹훅이 설정되어 있는지 어떻게 확인하나요?
getWebhookInfo를 호출하십시오. url이 비어 있으면 웹훅이 설정되지 않은 것이고 봇은 getUpdates로 동작합니다. 위 확인 도구가 대신 호출하고 결과를 설명해 줍니다.
텔레그램 봇 웹훅은 어떻게 삭제하나요?
deleteWebhook을 호출하십시오. 도구에서는 웹훅 설정 또는 변경을 열고 deleteWebhook을 누르면 됩니다. 대기 중인 업데이트를 버리려는 경우에만 대기 중인 업데이트 버리기에 체크하십시오. 그 후에는 getUpdates가 다시 동작합니다.
pending_update_count가 계속 늘어나는 이유는 무엇인가요?
텔레그램이 업데이트를 전달하지 못하고 있습니다. 서버에 접근할 수 없거나, 느리거나, 2xx가 아닌 상태 코드로 응답합니다. last_error_message를 확인하십시오. 텔레그램은 계속 재시도하며 업데이트는 최대 24시간 보관됩니다.
"Wrong response from the webhook"은 무슨 뜻인가요?
서버가 2xx가 아닌 HTTP 상태 코드로 응답했다는 뜻입니다. 예를 들어 경로가 틀리면 404, 비정상 종료하면 500입니다. 텔레그램은 빠른 2xx 응답을 기대하며, 그렇지 않으면 재시도합니다.
다른 유틸리티
chat ID 찾기MarkdownV2·HTML 이스케이프 도구Mini App initData 검증 도구Bot API Tester