Telegram Bot Webhook + VPS + Nginx + SSL: Step-by-Step Production Setup

Set up a Telegram bot webhook on a VPS with Nginx and SSL. This guide shows the exact deployment flow: domain, bot process, Let’s Encrypt certificate, Nginx reverse proxy, webhook registration, and final checks.

08 Apr 2026· 7 min read· How-To

Contact PAS7 Studio

Best forBackend engineersDevOps engineersFounders deploying internal botsTeams moving from polling to webhooksDevelopers shipping Telegram bots on a VPS

Telegram bot webhook deployed on a VPS with Nginx reverse proxy and SSL certificate

Summary

What you are building

This setup exposes one public HTTPS route for Telegram and keeps the bot process private on the server.

Point the domain to the VPS.

Run the bot on a local port such as 127.0.0.1:3000.

Use Nginx as the public reverse proxy.

Issue a valid SSL certificate with Let’s Encrypt.

Verify delivery with getWebhookInfo.

1. Prepare the server and the bot process

Start with the server state that certificate issuance and reverse proxying require.

Point the domain to the VPS public IP

Create an A record for the hostname you will use for the webhook, for example bot.example.com.

Run the bot on localhost

Bind the bot application to 127.0.0.1:<port>. Do not expose the bot app directly on a public interface.

Open ports 80 and 443

Keep port 80 available for Let’s Encrypt HTTP-01 validation and port 443 available for the final HTTPS webhook route [7][9][10].

Keep the public edge simple

Route public traffic only through Nginx. Let the bot app handle updates, not TLS, redirects, or public routing.

Required starting state

DNS must resolve to the VPS, the bot must listen locally, and ports 80 and 443 must be reachable.

2. Issue the SSL certificate

Issue the certificate before you switch the webhook to the final HTTPS route.

Install Certbot

Use the official Nginx integration so certificate issuance and renewal follow the documented flow [7].

Issue the certificate for the webhook hostname

Request the certificate for the exact hostname you will register in Telegram.

Run a dry-run renewal test

Confirm renewal works before you treat the deployment as finished [7][8].

Use DNS-01 only when HTTP-01 is not possible

Switch to DNS-01 when port 80 cannot be used or when you need a wildcard certificate [9].

Result

The VPS now has a valid certificate for the webhook domain and is ready for the final HTTPS Nginx config.

3. Configure Nginx as the public HTTPS entry point

Use one HTTP server block for the redirect and one HTTPS server block for the final reverse proxy. Proxy only the webhook path to the bot application on localhost [4][5][6].

Use a configuration like this:

NGINX

server {
    listen 80;
    listen [::]:80;
    server_name bot.example.com;

    location / {
        return 301 https://$host$request_uri;
    }
}

server {
    listen 443 ssl http2;
    listen [::]:443 ssl http2;
    server_name bot.example.com;

    ssl_certificate /etc/letsencrypt/live/bot.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/bot.example.com/privkey.pem;
    ssl_session_cache shared:SSL:10m;
    ssl_session_timeout 10m;

    client_max_body_size 20m;

    location = /healthz {
        add_header Content-Type text/plain;
        return 200 "ok\n";
    }

    location /telegram/webhook {
        proxy_pass http://127.0.0.1:3000/telegram/webhook;
        proxy_http_version 1.1;
        proxy_connect_timeout 5s;
        proxy_read_timeout 60s;
        proxy_send_timeout 60s;

        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }

    location / {
        return 404;
    }
}

Reload Nginx after you save the configuration. The bot stays private on 127.0.0.1, and Telegram reaches only the HTTPS route exposed by Nginx.

What this config does

HTTP redirects to HTTPS, HTTPS terminates TLS, and only the webhook path reaches the bot process.

4. Register the webhook in Telegram

Register the final public HTTPS URL only after Nginx and SSL are already working. Set a secret_token and verify it in the application with the X-Telegram-Bot-Api-Secret-Token header [1].

BASH

curl -X POST "https://api.telegram.org/bot$BOT_TOKEN/setWebhook"   -d "url=https://bot.example.com/telegram/webhook"   -d "secret_token=replace_with_a_long_random_value"   -d 'allowed_updates=["message","callback_query"]'

Check the status:

BASH

curl "https://api.telegram.org/bot$BOT_TOKEN/getWebhookInfo"

Use allowed_updates to limit delivery to the update types your bot actually handles. Read pending_update_count and the last error message in getWebhookInfo when delivery fails [1].

Webhook registration rule

5. Verify the deployment

Run these checks after the webhook is registered.

The domain resolves to the VPS public IP

Verify the exact hostname used in setWebhook.

The bot listens on localhost only

Keep the bot on 127.0.0.1:<port>.

Ports 80 and 443 are open

Check both host firewall rules and provider-side network rules [10].

The certificate is valid and renewal was tested

Keep certbot renew --dry-run in the deployment checklist [7][8].

Nginx proxies only the webhook path

Avoid broad public proxy rules for the whole application.

The app verifies the secret token header

Reject requests that do not match the configured token [1].

Telegram reports a healthy webhook state

Check getWebhookInfo after the first live requests [1].

Deployment target

A healthy deployment has a valid certificate, one public HTTPS route, and a bot process that stays private.

6. Fix the mistakes that break this setup

Most webhook failures come from a small set of repeatable mistakes.

Running the bot on 0.0.0.0 and exposing it directly to the internet.

Trying to use plain HTTP for the webhook even though Telegram requires HTTPS for webhook delivery [1][2].

Blocking port 80 during HTTP-01 validation and then failing certificate issuance [7][9].

Registering the webhook before the HTTPS endpoint is reachable.

Accepting any POST request on the webhook route without verifying the secret token [1].

Handling slow synchronous work inside the webhook request instead of acknowledging quickly.

Forgetting that getUpdates does not work while a webhook is active [1].

The pattern

Breakages usually come from wrong exposure, wrong order, or missing request validation.

FAQ

Do I need a VPS for a Telegram bot webhook?

You need a public HTTPS endpoint that Telegram can reach. A VPS is the most common way to control the domain, Nginx, certificate issuance, and firewall rules in one place.

Can I use getUpdates and a webhook at the same time?

No. When a webhook is active, Telegram disables `getUpdates` for that bot.

Which ports does Telegram support for webhooks?

Telegram documents support for ports 443, 80, 88, and 8443. In most production setups, use 443 as the public HTTPS entry point.

Why keep the bot on localhost?

This keeps the application off the public network surface. Nginx handles public HTTPS traffic, and the bot receives only proxied internal requests.

What should I check first when updates are not arriving?

Check the public HTTPS route, then run `getWebhookInfo` and read the last error message and `pending_update_count`.

Sources

These sources support the Telegram webhook behavior, Nginx proxy setup, SSL flow, and firewall guidance used in this tutorial.

Reviewed: 08 Apr 2026Applies to: Telegram Bot API webhooksApplies to: Single-server VPS deploymentsApplies to: Nginx reverse proxyApplies to: Let’s Encrypt certificate issuanceApplies to: Ubuntu and Debian-like Linux serversTested with: Telegram Bot API `setWebhook`Tested with: Telegram Bot API `getWebhookInfo`Tested with: Nginx `proxy_pass`Tested with: Nginx SSL terminationTested with: Certbot for NginxTested with: Let’s Encrypt HTTP-01 and DNS-01 conceptsTested with: UFW firewall rules

Need help turning this into a production deployment?

PAS7 Studio helps teams deploy Telegram bots with stable webhook routing, reverse proxy setup, certificate automation, app process management, migration from polling, and production hardening around the full stack.

Talk to PAS7 Studio Explore Automation Services