How to set a Telegram bot webhook

A webhook makes Telegram push every update to your HTTPS endpoint instead of you polling getUpdates. Here is how to set it up correctly and securely.

Do it in a few clicks — no code, no server, right in your browser.

Open the webhook manager

Requirements

A public HTTPS URL. Plain HTTP is not accepted.
Port 443, 80, 88 or 8443.
A valid TLS certificate (TLS 1.2+). A self-signed certificate works only if you upload its public key.
Your endpoint must answer with HTTP 2xx quickly; otherwise Telegram retries and updates pile up.

Set the webhook online

Open Telegram Bot Manager and paste the bot token from @BotFather.
On the Webhook tab enter the URL of your handler.
Press Generate to create a secret token and save it in your server config.
Choose allowed_updates if you need only some update types (or chat_member / reactions, which are off by default).
Press Set webhook. The status block shows the result immediately.

Parameters

Parameter	What it does
`url`	HTTPS endpoint that receives updates as JSON POST requests.
`secret_token`	1–256 chars `A-Z a-z 0-9 _ -`, sent in the `X-Telegram-Bot-Api-Secret-Token` header of every request.
`allowed_updates`	Update types to receive. Empty list = everything except chat_member, message_reaction, message_reaction_count.
`max_connections`	Simultaneous HTTPS connections, 1–100 (default 40).
`ip_address`	Fixed IP to use instead of DNS resolution.
`certificate`	Public key of a self-signed certificate.
`drop_pending_updates`	Discard updates that are waiting in the queue.

Same with curl

curl -X POST "https://api.telegram.org/bot$BOT_TOKEN/setWebhook" \
  --form-string "url=https://example.com/telegram/webhook" \
  --form-string "secret_token=$WEBHOOK_SECRET" \
  --form-string 'allowed_updates=["message","callback_query"]' \
  --form-string "max_connections=40"

With a self-signed certificate:

curl -X POST "https://api.telegram.org/bot$BOT_TOKEN/setWebhook" \
  --form-string "url=https://203.0.113.10:8443/webhook" \
  -F "certificate=@public.pem"

Verify the secret token on your server

Always compare the header with your secret and reject other requests — the webhook URL alone is not a secret.

// Node.js (Express): reject requests without the right secret
app.post('/telegram/webhook', (req, res) => {
  if (req.get('X-Telegram-Bot-Api-Secret-Token') !== process.env.WEBHOOK_SECRET) {
    return res.sendStatus(401);
  }
  // handle req.body (Update) ...
  res.sendStatus(200);
});

Common errors

Bad Request: bad webhook: An HTTPS URL must be provided for webhook — use https://.
Bad Request: bad webhook: Webhook can be set up only on ports 80, 88, 443 or 8443 — change the port or put a reverse proxy in front.
Bad Request: bad webhook: Failed to resolve host — the domain has no public DNS record.
Bad Request: secret token contains unallowed characters — use only letters, digits, _ and -.