텔레그램 웹훅 설정 가이드: setWebhook, secret_token, getWebhookInfo

최종 업데이트: 2026년 10월 29일 · 9 분 분량

텔레그램 웹훅(webhook)은 봇에 새 업데이트가 생길 때마다 텔레그램 서버가 여러분의 HTTPS 주소로 JSON을 POST해 주는 방식입니다. 텔레그램 봇 웹훅 설정은 setWebhook에 공개 HTTPS URL을 등록하면 끝나고, getWebhookInfo로 상태를 확인하며, deleteWebhook으로 언제든 getUpdates 방식으로 돌아갈 수 있습니다. 이 글에서는 설정 절차, secret_token을 이용한 요청 검증 코드, 자주 만나는 오류의 해결 방법을 설명합니다.

웹훅과 getUpdates(롱 폴링)의 차이

봇이 업데이트를 받는 방법은 두 가지이며, 서로 배타적이라 동시에 쓸 수 없습니다. 어느 방식이든 받아 가지 않은 업데이트는 서버에 최대 24시간까지만 보관됩니다.

웹훅을 쓰면 봇이 주기적으로 요청을 보낼 필요가 없고, 업데이트가 생기는 즉시 전달받습니다. 반대로 지금 getUpdates로 잘 동작하고 있다면 굳이 바꿀 필요는 없습니다. 개발 단계에서는 롱 폴링, 운영 서버에서는 웹훅으로 나누어 쓰는 구성도 흔합니다. 아직 봇이 없다면 텔레그램 봇 만들기부터 진행하십시오.

웹훅 서버 요구 사항

• HTTPS 필수: 일반 HTTP 주소는 등록할 수 없습니다. TLS 1.2 이상만 지원하며 SSLv2/3, TLS 1.0/1.1은 거부됩니다.
• 허용 포트: 443, 80, 88, 8443만 쓸 수 있습니다. 443이 아니면 URL에 포트를 명시합니다(예: https://bot.example.com:8443/telegram/webhook).
• 인증서: 신뢰할 수 있는 인증 기관의 인증서라면 별도 작업이 필요 없습니다. 인증서의 CN 또는 SAN이 도메인과 일치해야 하고, 중간 인증서까지 포함한 전체 체인을 제공해야 합니다. 자체 서명 인증서는 certificate 파라미터로 공개 키 인증서(PEM)를 업로드합니다.
• IPv4: 웹훅은 현재 IPv6를 지원하지 않습니다.
• 리디렉션 불가: 웹훅 주소가 다른 주소로 리디렉션하면 동작하지 않습니다.

방화벽으로 접근을 제한하려면 텔레그램이 안내하는 149.154.160.0/20과 91.108.4.0/22 대역을 허용하십시오. 이 대역은 바뀔 수 있으므로 문제가 생기면 공식 웹훅 가이드를 다시 확인해야 합니다.

참고로 오픈 소스로 공개된 Bot API 서버를 직접 운영하는 경우(로컬 Bot API 서버)에는 HTTP 주소, 임의의 포트, 로컬 IP 주소도 웹훅에 쓸 수 있습니다. 다만 대부분의 봇은 기본 서버인 api.telegram.org와 위의 요구 사항만으로 충분합니다.

setWebhook으로 텔레그램 봇 웹훅 설정하기

먼저 추측하기 어려운 비밀 값을 만듭니다. openssl rand -hex 32는 허용 문자만으로 된 64자 문자열을 만들어 줍니다.

SECRET=$(openssl rand -hex 32)

curl -X POST "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours/setWebhook" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://bot.example.com/telegram/webhook",
    "secret_token": "'"$SECRET"'",
    "allowed_updates": ["message", "callback_query"],
    "drop_pending_updates": true,
    "max_connections": 40
  }'

성공하면 {"ok":true,"result":true,"description":"Webhook was set"}가 반환됩니다. SECRET 값은 서버의 환경 변수에도 똑같이 넣어 두어야 합니다. 자체 서명 인증서를 쓴다면 파일 업로드가 필요하므로 JSON 대신 폼 형식으로 보냅니다.

curl -F "url=https://203.0.113.10:8443/telegram/webhook" \
  -F "certificate=@public.pem" \
  -F "secret_token=$SECRET" \
  "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours/setWebhook"

터미널 대신 Bot API Tester의 setWebhook에서 파라미터를 채워 호출해도 됩니다.

getWebhookInfo로 웹훅 상태 확인

설정이 끝나면 반드시 getWebhookInfo로 실제 상태를 확인하십시오. 파라미터 없이 호출하며, 웹훅이 없으면 url이 빈 문자열로 나옵니다.

curl "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours/getWebhookInfo"

{
  "ok": true,
  "result": {
    "url": "https://bot.example.com/telegram/webhook",
    "has_custom_certificate": false,
    "pending_update_count": 3,
    "last_error_date": 1793266500,
    "last_error_message": "Wrong response from the webhook: 404 Not Found",
    "max_connections": 40,
    "allowed_updates": ["message", "callback_query"]
  }
}

• pending_update_count: 아직 전달되지 못한 업데이트 수입니다. 계속 늘어난다면 서버가 2xx로 응답하지 못하고 있다는 뜻입니다.
• last_error_message와 last_error_date: 가장 최근 전달 실패의 내용과 시각(Unix time)입니다. 위 예시는 URL 경로가 서버 라우트와 맞지 않는 경우입니다.
• has_custom_certificate: certificate로 인증서를 업로드했는지 여부입니다.

같은 내용을 Bot API Tester의 getWebhookInfo에서 버튼 한 번으로 확인할 수 있습니다.

웹훅 핸들러 작성: secret_token 헤더 검증

웹훅 주소는 공개되어 있으므로 누구나 가짜 업데이트를 POST할 수 있습니다. 핸들러는 처리 전에 X-Telegram-Bot-Api-Secret-Token 헤더가 설정한 값과 같은지 확인해야 합니다. 다음은 Python(Flask) 예제입니다.

import hmac
import os

import requests
from flask import Flask, abort, request

TOKEN = os.environ["TELEGRAM_BOT_TOKEN"]
SECRET = os.environ["TELEGRAM_WEBHOOK_SECRET"]
API = f"https://api.telegram.org/bot{TOKEN}"
app = Flask(__name__)

@app.post("/telegram/webhook")
def telegram_webhook():
    received = request.headers.get("X-Telegram-Bot-Api-Secret-Token", "")
    if not hmac.compare_digest(received, SECRET):
        abort(403)
    update = request.get_json(silent=True) or {}
    message = update.get("message")
    if message and "text" in message:
        requests.post(f"{API}/sendMessage", json={
            "chat_id": message["chat"]["id"],
            "text": "받은 메시지: " + message["text"],
        }, timeout=10)
    return "", 200

Node.js(Express)에서는 웹훅 응답 본문에 호출할 메서드를 담아 바로 답장할 수도 있습니다. 별도의 API 요청이 줄어드는 대신, 이 방식으로 보낸 요청은 성공 여부나 결과를 확인할 수 없습니다.

import express from "express";

const app = express();
app.use(express.json());

app.post("/telegram/webhook", (req, res) => {
  if (req.get("X-Telegram-Bot-Api-Secret-Token") !== process.env.TELEGRAM_WEBHOOK_SECRET) {
    return res.sendStatus(403);
  }
  const msg = req.body.message;
  if (msg?.text) {
    return res.json({ method: "sendMessage", chat_id: msg.chat.id, text: `받은 메시지: ${msg.text}` });
  }
  res.sendStatus(200);
});

// HTTPS(443)는 앞단의 리버스 프록시나 호스팅 플랫폼이 처리합니다
app.listen(3000);

핸들러를 작성할 때는 다음 원칙을 지키십시오.

• 빠르게 2xx로 응답: 텔레그램은 2xx가 아닌 응답을 받으면 같은 업데이트를 다시 보내다가 일정 횟수 후 포기합니다. AI 모델 호출처럼 오래 걸리는 작업은 큐에 넣고 먼저 200을 반환합니다.
• 중복 처리 방지: 재전송 때문에 같은 업데이트가 두 번 올 수 있으므로 update_id를 기록해 이미 처리한 업데이트는 건너뜁니다.
• 예외는 로그로: 처리 중 오류가 나도 가능하면 200을 반환하고 로그에 남깁니다. 500을 반환하면 같은 업데이트가 반복해서 들어와 대기열이 막힙니다.

deleteWebhook으로 getUpdates 방식으로 되돌리기

로컬에서 디버깅하거나 서버를 옮길 때는 웹훅을 해제하고 롱 폴링으로 돌아갑니다. 웹훅이 설정된 동안에는 getUpdates가 동작하지 않습니다.

curl "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours/deleteWebhook?drop_pending_updates=true"

성공하면 Webhook was deleted가, 이미 웹훅이 없다면 Webhook is already deleted가 반환됩니다. drop_pending_updates를 빼면 쌓여 있던 업데이트는 그대로 남아 다음 getUpdates 호출에서 받을 수 있습니다. 브라우저에서는 deleteWebhook으로 실행할 수 있습니다.

폴링에서 웹훅으로 전환할 때 체크리스트

1. 도메인과 인증서 확인: 외부 네트워크에서 curl -v https://bot.example.com/telegram/webhook을 실행해 HTTPS 접속이 되는지, 인증서 오류가 없는지 확인합니다.
2. 핸들러 먼저 배포: secret_token 검증과 2xx 응답을 구현한 핸들러를 먼저 배포합니다. 웹훅부터 등록하면 준비되지 않은 서버로 업데이트가 몰려 실패가 쌓입니다.
3. 폴링 중지: 기존 getUpdates 프로세스를 종료합니다. 남아 있으면 409 오류를 반복해서 받습니다.
4. setWebhook 호출: 사용자 메시지를 하나도 놓치면 안 된다면 drop_pending_updates를 빼고, 테스트 중 쌓인 업데이트라면 true로 버립니다.
5. 상태 확인: getWebhookInfo에서 url과 allowed_updates가 의도대로인지, pending_update_count가 0으로 줄어드는지 봅니다.
6. 실제 메시지로 검증: 봇에게 메시지를 보내 답장이 오는지, 서버 로그에 요청이 기록되는지 확인합니다.

allowed_updates는 지정하지 않으면 이전 설정이 그대로 유지되고, 호출 전에 이미 생성된 업데이트에는 적용되지 않습니다. 설정을 바꾼 직후 잠시 원하지 않는 종류의 업데이트가 들어올 수 있으므로, 핸들러는 처리하지 않는 업데이트를 조용히 무시하고 200을 반환하도록 작성합니다. max_connections는 기본값 40으로 충분한 경우가 많으며, 서버 부하를 줄이려면 낮추고 처리량을 높이려면 올립니다.

텔레그램 웹훅 오류와 해결 방법

n8n을 localhost에서 실행하는 경우: 텔레그램 서버는 인터넷 너머에 있으므로 localhost나 http:// 주소로는 웹훅 요청을 보낼 수 없습니다. n8n처럼 웹훅으로 텔레그램 업데이트를 받는 도구를 로컬에서 쓰려면 터널링 서비스로 HTTPS 공개 주소를 만들거나, 도메인과 유효한 인증서가 있는 서버에 배포해야 합니다. 이때 같은 봇으로 다른 곳에서 getUpdates를 호출하면 409 오류가 나므로, 도구용 봇을 따로 만들어 두면 편합니다. 웹훅 설정 후 메시지를 보내는 방법은 텔레그램 봇 API 메시지 보내기에서, chat id 확인은 텔레그램 chat id 확인방법에서 다룹니다.