How to Set Up a Telegram Bot Webhook: setWebhook, Secret Token and Troubleshooting

Updated: October 29, 2026 · 8 min read

A Telegram bot webhook is an HTTPS URL on your server to which Telegram sends every update as a JSON POST request, so your bot no longer has to poll getUpdates. You register it with one call, setWebhook with your url and a secret_token, and check delivery with getWebhookInfo. This guide covers the requirements, a copy-paste handler that verifies the secret token, and fixes for the errors people hit most, including n8n on localhost.

Webhook vs getUpdates

The two methods are mutually exclusive: while a webhook is set, getUpdates returns 409 Conflict. Either way, Telegram keeps undelivered updates for up to 24 hours.

Telegram webhook requirements

• HTTPS only. The official Bot API rejects plain HTTP URLs on any port.
• Ports 443, 80, 88 or 8443. Other ports don't work. For anything but 443, put the port in the URL, e.g. https://example.com:8443/telegram/webhook.
• TLS 1.2 or newer and a certificate whose CN or SAN matches your domain. Serve the full chain, including intermediate certificates.
• Self-signed certificates work if you upload the public certificate in the certificate parameter.
• IPv4. IPv6 is not supported for webhooks, and redirects are not supported either, so register the final URL.
• Firewall: requests come from 149.154.160.0/20 and 91.108.4.0/22; Telegram notes these ranges may change.

A local Bot API server lifts some of these limits (HTTP, any port), but with api.telegram.org the rules above apply.

Set the webhook URL with setWebhook

Generate a random secret first, for example with openssl rand -hex 32, then register the URL:

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

On success the API answers {"ok": true, "result": true, "description": "Webhook was set"}.

For a quick one-off setup, the browser address bar works too: https://api.telegram.org/bot<token>/setWebhook?url=https://example.com/telegram/webhook. With a self-signed certificate, upload it as multipart/form-data:

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

Prefer a form? Fill in setWebhook in the Bot API Tester and execute it from your browser.

Check delivery with getWebhookInfo

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

{
  "ok": true,
  "result": {
    "url": "https://example.com/telegram/webhook",
    "has_custom_certificate": false,
    "pending_update_count": 14,
    "last_error_date": 1793266500,
    "last_error_message": "Wrong response from the webhook: 500 Internal Server Error",
    "max_connections": 40,
    "allowed_updates": ["message", "callback_query"]
  }
}

• url is empty when no webhook is set and the bot uses getUpdates.
• A pending_update_count that keeps growing means Telegram can't deliver: your endpoint is down, slow or returns errors.
• last_error_message and last_error_date (Unix time) describe the latest delivery failure: a timeout, a refused connection, a TLS problem or a non-2xx status from your server.

Run the same check in getWebhookInfo in the Bot API Tester whenever updates stop arriving.

Verify the X-Telegram-Bot-Api-Secret-Token header

Anyone who discovers your webhook URL can POST fake updates to it. With secret_token set, Telegram adds the secret to every request in the X-Telegram-Bot-Api-Secret-Token header; reject anything that doesn't match, using a constant-time comparison. Python with Flask (pip install flask):

import hmac
import os

from flask import Flask, abort, jsonify, request

app = Flask(__name__)
SECRET = os.environ["WEBHOOK_SECRET"]

@app.post("/telegram/webhook")
def telegram_webhook():
    received = request.headers.get("X-Telegram-Bot-Api-Secret-Token", "")
    if not hmac.compare_digest(received.encode(), SECRET.encode()):
        abort(403)
    update = request.get_json(silent=True) or {}
    message = update.get("message") or {}
    if "text" in message:
        # reply inside the webhook response: no extra API call needed
        return jsonify(method="sendMessage", chat_id=message["chat"]["id"],
                       text="Echo: " + message["text"])
    return "", 200

The reply trick is documented by Telegram: you may answer a webhook request with a JSON body that contains method and its parameters. You can't see whether that call succeeded, so make a regular API request when you need the result. The same check in Node.js 18+ without dependencies (save as server.mjs):

import http from "node:http";
import crypto from "node:crypto";

const SECRET = Buffer.from(process.env.WEBHOOK_SECRET);

function hasValidSecret(req) {
  const received = Buffer.from(req.headers["x-telegram-bot-api-secret-token"] ?? "");
  return received.length === SECRET.length && crypto.timingSafeEqual(received, SECRET);
}

function handleUpdate(update) {
  console.log("update", update.update_id); // your bot logic goes here
}

http.createServer((req, res) => {
  if (req.method !== "POST" || req.url !== "/telegram/webhook") {
    res.writeHead(404).end();
    return;
  }
  if (!hasValidSecret(req)) {
    res.writeHead(403).end();
    return;
  }
  let body = "";
  req.on("data", (chunk) => (body += chunk));
  req.on("end", () => {
    res.writeHead(200).end(); // acknowledge first, then process
    try {
      handleUpdate(JSON.parse(body));
    } catch (err) {
      console.error("bad update", err);
    }
  });
}).listen(8080);

Port 8080 isn't one of the four webhook ports, so run the app behind a reverse proxy such as nginx or Caddy that terminates TLS on 443 and forwards requests to it. Keep the secret in sync: if your server has a new secret but the webhook still has the old one, your own handler answers 403 and Telegram keeps retrying.

Respond with 2xx quickly

Telegram treats any response other than 2XX as a failed delivery: it repeats the request and gives up after a reasonable number of attempts, while new updates queue up behind it. Practical rules:

• Return 200 for every genuine update, including types you ignore and updates your code fails to process. Log the error instead of answering 500, or the same update keeps coming back.
• Acknowledge first and move slow work (LLM calls, file processing, broadcasts) to a background queue.
• Deduplicate by update_id, because retries can deliver the same update again.
• Use max_connections to cap parallel requests on a small server.

deleteWebhook: switch back to getUpdates

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

drop_pending_updates=true discards the backlog; leave it out to receive queued updates with getUpdates. Calling setWebhook with an empty url removes the webhook as well. Afterwards getWebhookInfo shows an empty url and polling works again.

Troubleshooting Telegram webhook errors

Telegram webhook with n8n

The n8n Telegram Trigger receives updates through a webhook: it registers its own URL for your bot with setWebhook. Three consequences follow:

• n8n on localhost fails with An HTTPS URL must be provided for webhook, because Telegram can't reach an http://localhost address. Make n8n reachable at a public HTTPS address (a reverse proxy with a certificate, or a tunnel) and configure n8n to use that address for its webhook URLs.
• One bot, one webhook. Two workflows or two n8n instances using the same bot overwrite each other's webhook. Use a separate bot per workflow.
• getUpdates stops working for that bot while the trigger is active, so look up chat ids before you activate it.

Related guides: keep your bot token secret, since it is part of every API call your handler makes, and Telegram Bot API limits for sending replies at scale. New to bots? Start with how to create a Telegram bot.