Debug every Telegram bot updatefrom setWebhook to production

Set a Telegram webhook (setWebhook)

Call setWebhook with the HTTPS URL that should receive updates. secret_token adds the verification header, allowed_updates limits the update types (send it as a JSON-serialized list), and drop_pending_updates=true discards whatever is queued from before. If the URL uses a port other than 443, put the port in the URL itself, for example https://bot.example.com:8443/telegram.

curl -X POST "https://api.telegram.org/bot<TOKEN>/setWebhook" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://bot.example.com/telegram",
    "secret_token": "my_secret_123",
    "allowed_updates": ["message", "callback_query"],
    "drop_pending_updates": true
  }'

Check it with getWebhookInfo

getWebhookInfo takes no parameters and returns a WebhookInfo object. url is empty when no webhook is set (or the bot is using getUpdates). pending_update_count is the number of updates waiting for delivery. last_error_date is the Unix time of the most recent delivery error and last_error_message describes it in readable form. The response also echoes max_connections, allowed_updates and has_custom_certificate, so you can confirm what Telegram actually stored.

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

# Example response shape
{
  "ok": true,
  "result": {
    "url": "https://bot.example.com/telegram",
    "has_custom_certificate": false,
    "pending_update_count": 3,
    "last_error_date": 1762819200,
    "last_error_message": "Wrong response from the webhook: 502 Bad Gateway",
    "max_connections": 40
  }
}

Remove it (deleteWebhook)

deleteWebhook removes the webhook so the bot can switch back to getUpdates. Pass drop_pending_updates=true to discard the queued updates at the same time. Calling setWebhook with an empty url does the same removal.

curl -X POST "https://api.telegram.org/bot<TOKEN>/deleteWebhook" \
  -d "drop_pending_updates=true"

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

Telegram does not sign the body. The secret token you chose comes back verbatim in a header, so compare it with the stored value before you touch the update and reject anything that does not match. Answer quickly with a 2XX status, because any other status makes Telegram send the update again.

app.post("/telegram", express.json(), (req, res) => {
  if (req.get("X-Telegram-Bot-Api-Secret-Token") !== process.env.TELEGRAM_SECRET) {
    return res.sendStatus(401);
  }
  queueUpdate(req.body); // process the Update outside the request
  res.sendStatus(200);
});

Ports and TLS

Telegram connects over IPv4 only and needs TLS 1.2 or newer. The certificate's CN or SAN must match the webhook domain, and your server must send every intermediate certificate in the chain. If you use a self-signed certificate, upload its public PEM file in the certificate parameter as multipart/form-data (InputFile). Sending it as a string does not work. If your CA's root is not trusted by Telegram, upload that root certificate the same way. The port rule applies to the public URL you give setWebhook, not to the port your local app listens on.

curl -F "url=https://203.0.113.10:8443/telegram" \
  -F "certificate=@public.pem" \
  "https://api.telegram.org/bot<TOKEN>/setWebhook"

Test a Telegram webhook locally

Run your bot on localhost, open a tunnel with the Hooklistener CLI, point setWebhook at the HTTPS URL the CLI prints, then send your bot a message. Each update then reaches your local handler. If the printed URL changes when you restart the tunnel, call setWebhook again with the new one. Updates captured at a Hooklistener webhook URL can be sent to your handler again with replay (Pro).

hooklistener login
hooklistener tunnel --port 3000

# In another terminal, use the URL the tunnel printed
curl -X POST "https://api.telegram.org/bot<TOKEN>/setWebhook" \
  -d "url=https://<printed-tunnel-url>/telegram" \
  -d "secret_token=my_secret_123"

# Now send your bot a message in Telegram

Request headers

Common errors

Sources (checked November 2026)

• Telegram Bot API: getUpdates, setWebhook, deleteWebhook, getWebhookInfo
• Telegram: Marvin's Marvellous Guide to All Things Webhook
• Telegram Bots FAQ: webhook problems
• Telegram Bot API server source (tdlib/telegram-bot-api): 409 and "Wrong response from the webhook" messages