To run a Telegram bot webhook on a VPS, point a DNS name at the server, serve that name over valid TLS, reverse-proxy the webhook path to a bot process listening privately on localhost, and register the final HTTPS URL with setWebhook. Telegram then pushes JSON Update objects to your endpoint. The supported webhook ports are 443, 80, 88, and 8443; port 443 with a trusted certificate and an Nginx proxy is the usual production setup.
Antihost offers Linux VPS plans with full root access, unlimited traffic on a 1 Gbps port and a 14-day free trial.
What a Telegram webhook does
A webhook is Telegram’s push-based delivery method. After you register an HTTPS URL, Telegram sends an HTTPS POST request containing a JSON-serialized Update whenever the bot receives an event allowed by your configuration. Your application must accept the request and return a successful HTTP response promptly. Work that might take longer should be queued or handed to a background worker rather than performed before the response.
As an Amazon Associate I earn from qualifying purchases.
This differs from getUpdates polling. Polling has your process repeatedly ask Telegram for new updates; a webhook has Telegram initiate the request. An outgoing webhook and polling cannot be active for the same bot at the same time. Delete the webhook before switching back to getUpdates.
Requirements and supported configurations
| Requirement | What to configure | Why it matters |
|---|---|---|
| Public address | A VPS with a public IPv4 address and a DNS A record such as bot.example.com pointing to it |
Telegram must be able to reach the server from the internet. Telegram’s webhook guide currently says IPv6 is not supported for webhooks. |
| Transport security | TLS 1.2 or newer, with a certificate whose CN or SAN exactly matches the webhook hostname | Telegram requires SSL/TLS encryption on every webhook port. |
| Port | 443, 80, 88, or 8443 | These are the ports Telegram accepts for webhooks. Open the selected TCP port in the VPS and operating-system firewalls. |
| Reverse proxy | Nginx or another proxy terminates TLS and forwards the request to a private bot listener such as 127.0.0.1:8080 |
The bot process does not need to be exposed directly to the internet. |
| Application route | A route matching the exact secret path, accepting Telegram’s JSON POST body and returning a success status quickly | A wrong path, non-2xx response, timeout, or malformed body causes delivery failures and retries. |
| Request authentication | An unguessable path and, preferably, the secret_token option checked through the X-Telegram-Bot-Api-Secret-Token header |
Only requests carrying the configured secret should reach the update handler. |
Telegram’s Bot API allows max_connections from 1 to 100, with a default of 40. The secret_token value may be 1 to 256 characters. These are API limits, not a promise that your VPS or application can process that many requests concurrently.
#1 Best Overall
- [Ultra-Lightweight Ear Buds Designed for Small Ears] Each earbud weighs only 3.7g and features a compact, ergonomic in-ear design made especially for small ears. Secure, low-profile, and comfortable for workouts, all-day wear or overnight sleeping.The ultra-slim profile sits flush in your ear with no hard edges poking or rubbing, so you can even sleep on your side without discomfort.
- [Immersive Stereo Sound with TOZO OrigX Technology] TOZO OrigX tuning delivers clear vocals, balanced mids, and natural stereo sound for music, podcasts, and videos.
- [Long Battery Life for Daily Use] Get up to 7 hours of playtime on a single charge, with up to 32 hours total using the charging case—ideal for workdays, commuting, and extended listening sessions.
- [Bluetooth 5.3 & Stable Connection] Bluetooth 5.3 provides fast pairing, stable wireless performance, and reduced dropouts as you move around home or office.
- [Deep Bass with Clear Vocals] High-performance drivers produce punchy bass while keeping vocals clean and detailed for everyday listening.
How the VPS architecture fits together
The complete request path should be:
- Telegram resolves
bot.example.comthrough DNS. - Telegram opens an HTTPS connection to the VPS on a supported port, normally 443.
- Nginx presents the certificate and checks the requested host and path.
- Nginx proxies the request to the bot process on a loopback address such as
127.0.0.1:8080. - The application validates the secret header, parses the JSON
Update, queues any slow work, and returns a successful HTTP status.
Only Nginx should listen publicly. Binding the bot to localhost prevents an accidental second public entry point and leaves TLS, access logging, connection limits, and certificate renewal in one place.
Step 1: Prepare the VPS, DNS, and firewall
Choose an IPv4-capable VPS
Record the VPS’s public IPv4 address. Telegram’s current webhook instructions require IPv4 and state that IPv6 is not currently supported for webhook delivery. Ensure the server has enough CPU, memory, and network capacity for your bot’s expected update rate; the API’s connection limit does not replace capacity planning.
Free tools Windows power users keep installed
One-click scans. No signup required.
Create the DNS record
Create an A record for the exact hostname you will place in the webhook URL, for example:
bot.example.com A 203.0.113.10Wait until public DNS resolvers return the VPS address. The certificate, Nginx server_name, and setWebhook URL must all use the same hostname. A certificate for example.com does not automatically cover an unrelated name such as bot.example.com unless the latter appears in the certificate’s SAN list.
Open only the required network ports
Allow inbound TCP on the port you selected, normally 443. Keep the bot’s local port, such as 8080, inaccessible from the internet. If you use an operating-system firewall and a provider firewall, add the rule in both places and verify that neither layer blocks the connection.
Step 2: Run the bot privately
Start the bot application on a loopback address, for example 127.0.0.1:8080. Configure one route for the exact webhook path you will register. The handler should:
Rank #2
- 【IP68 Waterproof Multifunctinal Smart Watch】Torjalph fitness activity tracker smart watch is IP68 waterproof technology ,you can wear it when swimming,handwashing,it's rain-proof which means that you perform multiple exercise modes outside without worrying about sweat or rain corroding your fitness smart watch,and this watch equipped with a 230 mAh large capacity battery magnetic charging ,and this sports activity tracker watch can be used 5-7 days If fully charged.
- 【Larger 1.83'' Full Screen Watch & Multi-dial Selection】1.83 inch full HD color touch screen smart watch for men / women provides excellent 240*284 resolution image quality ,This Bluetooth smart watch offers a better touch experience and remarkable immersion and ,more than 200 watch faces for you to choose from App"Da Fit ", you can change the dial style according to your mood to wear keeping the world on your wrist
- 【Accurate Activity Tracker Smart Watch 】sports watch activity tracker uses sweat and dust resistant breathable silicone strap, our Fitness Tracker Smart Watch for Android iOS Phones supports 12 sports modes,walking,running,bicycle,swimming,badminton,basketball,football,rope skipping. This bluetooth calls smart watch for men women is lightweight and stylish, bringing more convenient and relaxing sports experience while also providing more protection.
- 【Your 24 Hour Personal Daily Health Monitor】Fitness watch for women men full touch screen IP67 waterproof bluetooth smartwatch for Android iOS Phones with heart rate blood pressure monitor multifunction Andriod smart watch with steps counter sleep monitor sports fitness watch, monitoring blood oxygen saturation allows you to understand your physical condition in real time to track fitness progress ,to know your health status in time.
- 【More Functions Bluetooth Call Smart Watch】This fitness activity smart watch full screen for iPhone and Android phones includes a bunch of new features including:The bluetooth smart watch can hang up the phone, receive and display WhatsAPP /Text /Facebook /Twitter /Messenger reminder.Support sedentary reminder, alarm clock, stopwatch, timer,weather information,music control, remote camera control compatible with Android 5.0 and above or iOS 9.0 and above smartphones.
- Accept
POSTrequests with Telegram’s JSON body. - Read and validate the
X-Telegram-Bot-Api-Secret-Tokenheader when you setsecret_token. - Return a successful HTTP response as soon as the update is safely accepted.
- Queue slow operations such as API calls, database work, media processing, or external requests.
- Log enough context to correlate failures without writing the bot token or sensitive user data to logs.
Do not assume that a TCP connection proves the handler works. Test the local route with a representative JSON request before putting the proxy in front of it. Confirm that the application returns the status your framework considers successful and that its request body limit is large enough for the updates your bot expects.
Step 3: Terminate TLS with Nginx
Use a certificate for the exact webhook hostname
Obtain a trusted certificate for bot.example.com and configure Nginx with the certificate and private key. Serve the complete certificate chain, including required intermediate certificates. Telegram checks that the certificate’s CN or SAN matches the supplied domain; an incomplete chain or hostname mismatch prevents delivery.
Telegram requires TLS 1.2 or newer for webhooks. The certificate may be issued by a public certificate authority, or you can use a self-signed certificate by uploading its public PEM file when calling setWebhook, as described later.
Proxy the final HTTPS URL directly
Telegram’s FAQ states that redirects are not supported. Do not register an HTTP URL that redirects to HTTPS, and do not rely on a host or path redirect for the webhook request. Register the final HTTPS endpoint and make Nginx serve it directly.
Outdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware matchPC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11A minimal Nginx server block looks like this; adjust file paths, the hostname, and the local port for your installation:
server {
listen 443 ssl http2;
server_name bot.example.com;
ssl_certificate /etc/ssl/bot.example.com/fullchain.pem;
ssl_certificate_key /etc/ssl/bot.example.com/privkey.pem;
location = /telegram-hook-6f4c2d9a8b1e {
proxy_pass http://127.0.0.1:8080;
proxy_http_version 1.1;
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;
}
}The exact-match location = prevents unrelated paths from being sent to the bot. Keep the path unguessable; the example is illustrative, so generate your own high-entropy value.
Rank #3
- [Low Noise High Fidelity] New bee guitar cord with 22AWG oxygen-free-copper center conductors provides enhanced signal transfer, the PVC insulation material and the high-density stranded copper double shield provide noise rejection for quiet operation
- [Ideal for Choice] New bee 1/4 straight and right angle metal connectors, ensures a secure connection in any instrument, pedal, or amp jack. L shape great fro on stage guitar stands
- [Wide Compatible] Suitable for mixer, power amplifier, microphone, effector, decoder, equalizer, electoronic organ, electric guitar, electric bass and other electronic equipments. Widely used in the installation of smart home, karaoke speaker, professional stage audio, etc
- [Easy Disassemble] Making incidental repairs quick and easy! Very nice, flexible cable
- [Dont Hesite to Order] 24 hours customer services and professional technology team are standing by
Step 4: Register the webhook with Telegram
Use setWebhook with a secret path
Call the Bot API with the complete HTTPS URL:
curl -F "url=https://bot.example.com/<unguessable-path>"
"https://api.telegram.org/bot<YOUR_BOT_TOKEN>/setWebhook"Telegram sends HTTPS POST requests with JSON Update objects after the method succeeds. Keep the bot token out of shell history, process listings, shared terminal transcripts, and public logs. If your shell records commands, use a protected environment variable or another secret-injection method and restrict access to the account that performs deployment.
Optionally set a secret header token
The Bot API’s secret_token option causes Telegram to include X-Telegram-Bot-Api-Secret-Token on every webhook request. Use a random value between 1 and 256 characters, store it in the application’s secret configuration, and reject requests whose header is missing or does not match. The secret path and header serve different purposes: the path reduces unsolicited traffic, while the header gives your application an explicit authenticity check.
The exact request can include additional form fields when needed, for example:
curl -F "url=https://bot.example.com/<unguessable-path>"
-F "secret_token=<random-header-secret>"
"https://api.telegram.org/bot<YOUR_BOT_TOKEN>/setWebhook"Register only the update types your bot needs with allowed_updates. This reduces unnecessary traffic, but changing that setting does not repair a DNS, TLS, routing, or application error.
Use a self-signed certificate only when you can distribute it correctly
For a self-signed certificate, upload the public PEM certificate in the certificate form field:
curl -F "url=https://bot.example.com/<path>"
-F "[email protected]"
"https://api.telegram.org/bot<YOUR_BOT_TOKEN>/setWebhook"Telegram’s self-signed guidance specifically requires uploading the certificate through the certificate parameter. The private key must remain only on the VPS. A trusted certificate is operationally simpler because clients can validate its chain without an upload, while a self-signed setup adds certificate distribution and renewal responsibilities.
Rank #4
- Digital Family Calendar: BSIMB digital calendar wall touch screen puts an end to your chaotic life. Designed for busy families, the digital calendar keeps you organised and in step with your family. Assign different colours and tasks to each family member to make family scheduling easier and more intuitive.
- Easy Setup and Auto-Sync: Plug in, connect to WLAN and auto-syn your electric calendar in minutes. Digital wall calendar compatible with Google calendar, iCloud calendar, Outlook calendar, Cozi calendar and Yahoo calendar. Add events directly on the device or through the ecalendar app. Electronic calendar stays current whether you're at work or traveling—no manual updates needed.
- All-In-One Home Assistant: Smart calendar builds habits and encourage independence with personalised chores. Display daily meal plan to reduce the daily ‘What's for dinner?’ stress. To-do lists keep track of everything you want. Turning chores into valuable achievements with stars and rewards, making life easier and more enjoyable.
- Manage Anytime Anywhere: BSIMB electronic calendar for family stay connected with the powerful ecalendar app. Access and manage your digital wall calendar anytime, anywhere with free features like stars & rewards, photo screensaver, chore charts, meals plans, to-do lists etc. Electronic planner paid features like Magic Import tailor advanced tools for users with special needs.
- Stay in Touch with Loved Ones: Share photos or videos from your phone to electronic wall calendar with app, instantly update your life moment, and keep in touch with your family, especially those who are far away; you can also surprise your smart calendar digital wall by sending him a wish card; it's also great for keeping tech-illiterate elders in touch with the youngsters.
Step 5: Validate the request in your application
At the edge, allow only the exact method and path you registered. In the application, compare the received secret header with the configured value using a constant-time comparison where your framework provides one. Return an authorization failure for a missing or incorrect header and do not process the body as a bot update.
After authentication, parse the JSON body and dispatch by update type. Telegram may deliver messages, callback queries, edited messages, and other update forms, so code should handle unknown or newly introduced fields without crashing. Acknowledge the request before doing work that could exceed your proxy or application timeout. If processing fails after acknowledgement, use your queue, retry policy, and application logs rather than forcing Telegram to resend the same update indefinitely.
Step 6: Verify delivery end to end
Inspect Telegram’s webhook state
Run:
curl "https://api.telegram.org/bot<YOUR_BOT_TOKEN>/getWebhookInfo"Inspect every important field:
| Field | How to use it |
|---|---|
url |
Confirm it is the exact hostname, port, and path you configured. An empty or unexpected value means the webhook is not registered as intended. |
pending_update_count |
A growing count indicates Telegram has updates waiting because delivery or acknowledgement is failing. |
last_error_date |
Shows when Telegram last recorded a delivery error. |
last_error_message |
Use the message to choose the next check: certificate, connection, redirect, timeout, or application response. |
max_connections |
Shows the configured concurrent delivery limit, from 1 through 100; the default is 40 if you did not change it. |
allowed_updates |
Confirms which update categories Telegram is configured to send. |
Send a real test update
Send a message to the bot, then watch both Nginx and application logs. You should see a POST to the exact secret path, a successful upstream response, and the application log entry for the update. Check the request’s host, path, status code, and timing; a request reaching the wrong Nginx server block is not an end-to-end success.
Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Scan for outdated or missing drivers - takes under a minute3Clear out junk files and repair common Windows errorsStep 7: Operate the bot reliably
Keep the process running
Run the bot under a system service or a container supervisor so it restarts after a crash and starts after a VPS reboot. Store the bot token, header secret, database credentials, and certificate key outside source control. Restrict permissions on those files and rotate secrets if they appear in a log, command history, or support ticket.
Monitor the right signals
- Track the bot process and its restart count.
- Alert on Nginx 4xx and 5xx responses for the webhook path.
- Watch
pending_update_countandlast_error_messagefromgetWebhookInfo. - Monitor certificate expiration and renew the full chain before it expires.
- Measure handler latency so slow work can be moved to a queue before Telegram delivery backs up.
Choose a sensible concurrency value
The API permits 1–100 simultaneous webhook connections and defaults to 40. Start with the default unless you have measured a need to change it. Raising the value can increase throughput only when the application, database, proxy, and VPS can process requests concurrently; otherwise it can increase contention and failures. Lowering it can protect a small service from bursts but may leave updates pending during sustained traffic.
Deployment choices: what changes and what does not
| Choice | Advantages | Trade-offs and checks |
|---|---|---|
| Trusted certificate plus Nginx on port 443 | Standard HTTPS endpoint, straightforward client validation, clear separation between TLS and the bot | Renew the certificate and serve the complete chain; keep the local upstream healthy. |
| Self-signed certificate | Useful when you control certificate distribution and need a private trust model | Upload the public PEM with certificate in setWebhook; plan renewal and replacement carefully. |
| Nginx proxy | Widely supported routing, TLS termination, access logs, and exact path matching | Proxy headers and timeout settings must match the application framework. |
| Another reverse proxy | Can fit an existing container or service platform | It still must serve the final HTTPS URL directly, present the matching full certificate chain, and forward the exact POST path without redirects. |
| Public port 443 | Conventional firewall and certificate configuration | Open TCP 443 at every firewall layer. |
| Port 80, 88, or 8443 | Supported alternatives when 443 is unavailable | TLS is still required, and the port must appear in the registered URL and be reachable from the internet. |
| System service | Simple startup ordering, restart policies, and host-level logs | Define a least-privilege user and protect environment files. |
| Container supervisor | Reproducible packaging and isolated dependencies | Publish only the proxy port, persist required data, and ensure the container restarts with the VPS. |
Troubleshoot a webhook that is not receiving updates
The certificate hostname does not match
Issue a certificate whose CN or SAN contains the exact webhook hostname. Check for a mismatch between the URL’s subdomain and the name on the certificate. Re-register the webhook after replacing the certificate if necessary, then inspect last_error_message.
The certificate chain is incomplete
Configure Nginx with a bundle containing the server certificate and required intermediate certificates, not only the leaf certificate. Telegram can reject an otherwise correctly named certificate when the chain cannot be built.
Recommended Free Tools
The port is unsupported or blocked
Use only 443, 80, 88, or 8443. Confirm the port is open in the VPS provider firewall, the operating-system firewall, and Nginx’s listening configuration. A bot listening on 8080 is not a substitute for a public Telegram-supported port; 8080 should normally remain local behind the proxy.
Nginx returns a redirect
Remove HTTP-to-HTTPS, host, and path redirects from the registered endpoint. Telegram’s FAQ says redirects are not supported. Register the final HTTPS URL and make that location answer directly.
The request reaches Nginx but not the bot
Check that the application is listening on the address and port in proxy_pass, that the path matches exactly, and that local security rules permit Nginx to connect. Review the Nginx error log for connection-refused or timeout messages and test the upstream locally from the VPS.
The application rejects or times out
Confirm the route accepts POST and JSON, reads the body, validates the expected header without accidentally requiring a different header name, and returns a successful status promptly. Move slow operations to a queue. A 401, 403, 404, 413, 429, 500, or timeout can leave updates pending.
Quick wins for a faster PC:
Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Clear out junk files and repair common Windows errorsFree Scan →Scan for outdated or missing drivers - takes under a minuteDriver Scan →setWebhook succeeded but no update arrives
First call getWebhookInfo. Compare url, pending_update_count, last_error_date, and last_error_message. Then verify DNS resolution, IPv4 reachability, firewall rules, certificate name and chain, absence of redirects, exact proxy routing, and the application’s response code. Send a new test message after each corrective change so you can associate the result with one change.
Polling reports a conflict
An active outgoing webhook prevents getUpdates polling. Delete the webhook before starting a polling worker. Conversely, stop polling before registering a webhook, so two delivery mechanisms are not competing for the same bot.
Removing or replacing a webhook
When migrating hosts, changing the path, or switching to polling, remove the old registration through the Bot API before bringing up the new delivery method. Treat migration as a sequence: prepare DNS, certificate, proxy, and application on the new VPS; register the new final URL; verify getWebhookInfo and a real update; then retire the old service. Keep the old endpoint available long enough to diagnose a DNS cache or configuration mistake, but do not leave an unmaintained handler accepting authenticated-looking requests.
Quick Recap
Practical go-live checklist
- The DNS A record resolves the webhook hostname to the VPS public IPv4 address.
- The VPS and host firewall allow the selected Telegram port: 443, 80, 88, or 8443.
- Nginx presents a TLS 1.2-or-newer certificate whose CN or SAN matches the hostname.
- The complete certificate chain is served, and the endpoint does not redirect.
- The bot listens privately on localhost, while Nginx is the only public listener.
- The exact unguessable path is configured identically in Nginx, the application, and
setWebhook. - The application validates
X-Telegram-Bot-Api-Secret-Tokenwhensecret_tokenis configured. setWebhookreturns success without exposing the bot token in logs or shell history.getWebhookInfoshows the expected URL and no growing pending count or recent delivery error.- A real message produces an application log entry and a successful response at the exact path.
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
