Telegram Bot Webhook vs Long Polling: Setup, secret_token, and Switching Without a 409

A Telegram bot gets updates either by long polling (getUpdates) or by a webhook (setWebhook), never both. Telegram returns 409 Conflict if you poll while a webhook is set, or if two processes poll one token. Pick one method, call deleteWebhook before switching to polling, and set secret_token to verify webhook calls.

Last verified: October 2026 against the Telegram Bot API reference, the Bots FAQ and the Marvin's Patent Pending Guide to All Things Webhook. Error strings are the literal descriptions the API returns.

The Bot API documentation opens its "Getting updates" section with the rule that drives everything else in this guide: "There are two mutually exclusive ways of receiving updates for your bot". Whichever one you choose, updates wait on Telegram's side until you collect them, and "they will not be kept longer than 24 hours".

Neither mode is faster in a way you will notice for an ordinary bot, and Telegram itself is relaxed about the choice: its webhook guide says "There is nothing wrong with using getUpdates". The choice is about where the bot runs and how many copies of it run, not about performance.

Want to see which mode a token is in right now? The Telegram webhook checker reads getWebhookInfo for any token and shows the registered URL, the pending queue and the last delivery error. An empty url means the token is in polling mode.

With long polling your code calls getUpdates in a loop. Four parameters control it, and two of them are where most polling bugs come from.

A minimal, correct polling loop looks like this:

let offset = 0;
while (true) {
  const res = await fetch(
    `https://api.telegram.org/bot${TOKEN}/getUpdates?timeout=30&offset=${offset}`
  ).then(r => r.json());
  if (!res.ok) { console.error(res.error_code, res.description); await sleep(5000); continue; }
  for (const update of res.result) {
    await handle(update);
    offset = update.update_id + 1;   // confirms this update
  }
}

Two details from the reference are worth remembering. First, the FAQ notes that getUpdates "returns the earliest 100 unconfirmed updates", so a bot that never advances offset keeps seeing the same first 100 forever. Second, update_id is not guaranteed to be continuous over long gaps: "If there are no new updates for at least a week, then identifier of the next update will be chosen randomly". Never use it as a database primary key that you expect to grow by one.

The reference also says plainly that getUpdates "will not work if an outgoing webhook is set up". That sentence is the first of the two 409 errors covered below.

With a webhook you call setWebhook once with a URL, and from then on "Whenever there is an update for the bot, we will send an HTTPS POST request to the specified URL" containing a JSON-serialized Update. If your endpoint answers with anything other than a 2XX status, Telegram repeats the request and eventually gives up, which is how a webhook backlog builds up. Our guide to pending_update_count covers reading that backlog.

curl -X POST "https://api.telegram.org/bot<TOKEN>/setWebhook" \
  -d "url=https://bot.example.com/telegram" \
  -d "secret_token=7f3a9c_change_me-2026" \
  -d "max_connections=40" \
  -d "drop_pending_updates=true"

The parameters that matter, as the reference defines them:

The network rules your endpoint has to meet

• Ports. "Ports currently supported for webhooks: 443, 80, 88, 8443." An app listening on 3000 or 8080 needs a reverse proxy in front of it.
• HTTPS only. The hosted Bot API refuses http:// URLs. Telegram's documentation lists plain HTTP and any port as features of a self-hosted Local Bot API Server, not of api.telegram.org.
• TLS 1.2 or newer, and IPv4. The webhook guide states that older SSL/TLS versions are not accepted and that "IPv6 is currently not supported for webhooks."
• Source addresses. The same guide says webhook requests come from the subnets 149.154.160.0/20 and 91.108.4.0/22, and warns the ranges may change. You can allow-list them at your firewall, but do not make that your only check: use secret_token as well.

Replying inside the webhook response

A webhook has one shortcut polling does not. The reference allows you to answer with a Bot API method in the body of your HTTP response: "If you're using webhooks, you can perform a request to the Bot API while sending an answer to the webhook." The trade-off, as the FAQ notes, is that you cannot tell whether that call succeeded or read its result. Use it for fire-and-forget replies, and make a normal API call when you need the returned message.

Anyone who learns your webhook URL can POST a fake update to it. Without a check, your bot will treat a forged "message" as real: it might reply to a chat ID the attacker chose, or run a command on their behalf. Telegram's answer is the secret_token parameter: "A secret token to be sent in a header 'X-Telegram-Bot-Api-Secret-Token' in every webhook request". The FAQ's older advice, a hard-to-guess path in the URL, still works, but the header keeps the secret out of access logs and proxy logs that record paths.

Generate a random value of up to 256 characters from the allowed set (A-Z a-z 0-9 _ -), pass it in setWebhook, and reject any request whose header does not match. In Express:

import crypto from "node:crypto";

app.post("/telegram", express.json(), (req, res) => {
  const got = Buffer.from(req.get("X-Telegram-Bot-Api-Secret-Token") || "");
  const want = Buffer.from(process.env.TG_WEBHOOK_SECRET);
  if (got.length !== want.length || !crypto.timingSafeEqual(got, want)) {
    return res.sendStatus(401);
  }
  res.sendStatus(200);          // acknowledge first
  queue.push(req.body);         // then process the update
});

The same check in Python with FastAPI:

import hmac, os
from fastapi import FastAPI, Request, Response

app = FastAPI()
SECRET = os.environ["TG_WEBHOOK_SECRET"]

@app.post("/telegram")
async def telegram(request: Request):
    got = request.headers.get("X-Telegram-Bot-Api-Secret-Token", "")
    if not hmac.compare_digest(got, SECRET):
        return Response(status_code=401)
    update = await request.json()
    enqueue(update)
    return Response(status_code=200)

Three things go wrong with secret tokens in practice:

1. A character outside the allowed set. Base64 output contains +, / and =, which are not allowed. Use hex, or base64url without padding.
2. A deploy script that drifts. If one script calls setWebhook with the secret and another (a CI job, a library's startup helper) calls it without, the value Telegram sends and the value your code expects can stop matching. Your check then rejects real updates with 401, which shows up as a growing pending_update_count and a last_error_message naming your 401. Pass secret_token on every setWebhook call, from one place.
3. Rotating it in the wrong order. Deploy code that accepts both old and new values, call setWebhook with the new one, then remove the old value.

Pick by where the bot runs, not by habit. This table covers the cases that come up most often.

If you are unsure, start with polling while you develop, and move to a webhook when you deploy to more than one instance or to serverless. The move is the part that goes wrong, so it gets its own section.

There are two different 409 errors, and they have different causes. Both come from the rule that one token has one consumer of updates.

409 while a webhook is set

{"ok":false,"error_code":409,"description":"Conflict: can't use getUpdates method while webhook is active; use deleteWebhook to delete the webhook first"}

A webhook is registered and your code is calling getUpdates. The description tells you the fix. The reference page for this 409 lists the usual sources: an old deploy, a teammate, a framework default, or a hosting platform that registered its own webhook.

409 from two pollers

{"ok":false,"error_code":409,"description":"Conflict: terminated by other getUpdates request; make sure that only one bot instance is running"}

Two processes are polling one token. Each new request ends the other one, and each process gets roughly half the messages. Look for a second replica, a laptop still running the production token, or a deploy whose old and new instances overlap. Details on the terminated by other getUpdates request page.

Webhook to polling, in order

1. Stop or drain the service that receives the webhook.
2. Call deleteWebhook. Add drop_pending_updates=true only if you are sure you do not want the queued updates:

   curl "https://api.telegram.org/bot<TOKEN>/deleteWebhook"

3. Call getWebhookInfo and confirm url is "".
4. Start exactly one polling process.

Polling to webhook, in order

1. Deploy the webhook endpoint and check from outside your network that it answers a POST with 200 within a second or two.
2. Stop every polling process. Check with ps, your process manager and your replica count, not only your memory.
3. Call setWebhook with url and secret_token. There is no need to call deleteWebhook first: the token is in polling mode, so there is no webhook to remove.
4. Call getWebhookInfo. Over the next minutes, pending_update_count should stay at or near 0 and last_error_message should be absent.

Updates sent while you switch are not lost. Telegram keeps them for up to 24 hours and delivers them to whichever method is active next, unless you passed drop_pending_updates. The reverse risk is a bot that replays a long backlog when it comes back. Decide which one you want before you run the command.

Libraries often hide this. python-telegram-bot, aiogram, grammY and Telegraf all have helpers that start polling or set a webhook for you, and some call deleteWebhook automatically when polling starts. If your bot works locally but goes silent in production, check whether a startup routine is quietly moving the token between modes on every boot.

When setWebhook fails, the description starts with bad webhook: and then names the rule that failed. These are the ones you will meet most often:

A successful setWebhook only means Telegram accepted the URL. It says nothing about whether delivery works. Delivery problems such as certificate chains, timeouts and 5XX responses from your app show up later in getWebhookInfo, in last_error_message, last_error_date and pending_update_count. The full list of documented fields is url, has_custom_certificate, pending_update_count, ip_address, last_error_date, last_error_message, last_synchronization_error_date, max_connections and allowed_updates.

For every other literal error string, the Telegram error code directory maps each description to its cause and fix. Webhook and polling limits are collected on the Telegram limits page.

Whichever method you choose, these habits prevent most of the outages that end up as a "bot not responding" search.

• Acknowledge first, work second. With a webhook, return 200 at once and process the update on a queue. A handler that calls an AI model or a database before it responds is the most common cause of a growing backlog.
• Make handlers idempotent. Telegram retries webhook deliveries, and a polling bot that crashes before it advances offset gets the same batch again. Store processed update_id values for a short time and skip duplicates.
• One token per environment. Create a separate bot in @BotFather for staging and local development. Most 409s come from a developer sharing the production token.
• Alert on getWebhookInfo. Check it every minute and alert when last_error_date changes or pending_update_count passes a threshold you chose from your own traffic.
• Log the full error body. The Bot API's description field tells you what went wrong. Its documentation notes that the numeric error_code is "subject to change in the future", so match on the description, not only the number.
• Respect the 24-hour window. A dead webhook over a weekend loses messages for good. Updates older than 24 hours are gone, whichever method you use.

If the bot is silent and neither 409 applies, the cause is usually elsewhere: group privacy mode, a blocked user or a revoked token. Our Telegram bot not responding guide works through those in order, and the webhook debugging guide covers the same failures on other platforms.

Everything above is plumbing: choosing a delivery mode, guarding the endpoint, keeping one consumer per token and watching the queue. That is worth doing when the bot is your product. When the bot is a support, booking or FAQ channel for a business, it is mostly overhead.

With Conferbot you create the bot in @BotFather, paste its token into Conferbot, design the conversation in the AI chatbot builder and publish. You do not run a server or choose between polling and a webhook. One rule from this guide still applies: once a platform is using a token, do not point your own code at the same token with getUpdates or setWebhook, or you will take its updates away from it. Use a second bot for experiments.

Conferbot is one builder for every major chat platform, so the same flow can also run on WhatsApp, Discord, Slack and your website. The Free plan costs $0, needs no credit card and covers 600 conversations a month for two bots. Details are on the Telegram chatbot page.