How to set Telegram bot webhook?

How to set Telegram bot webhook?

  1. Blog
  2. 15 November 2026
  3. 4 min read

Stefan Bogdanescu

Founder & Senior Architect

Configuring Telegram Bot Webhooks with Self-Signed Certificates

Setting up a webhook for a Telegram bot on your own domain is the standard approach for high-volume bots, but it introduces specific networking requirements that differ significantly from using Telegram's cloud servers. The core challenge arises when you attempt to use a self-signed SSL certificate. While generating a certificate locally is straightforward, the Telegram Bot API does not automatically trust these certificates unless explicitly configured via the cert parameter during the webhook update.

When you call setWebhook, you must ensure your server listens on port 443 with valid TLS credentials. If you are using a framework like Laravel or Node.js, simply pointing to a local development certificate often fails because the underlying HTTP client (like curl) or the web server itself might not be configured to present that specific certificate chain during the handshake with Telegram's servers.

Preparing the Certificate Files

The most common pitfall is assuming that generating a self-signed certificate in OpenSSL automatically creates the exact file structure Telegram expects. You need two distinct files:

  1. cert.pem: The public certificate containing your domain name and validity dates.
  2. key.pem: The private key corresponding to the certificate.

Ensure these files are generated with a valid Common Name (CN) or Subject Alternative Name (SAN) that matches exactly the hostname you intend to use for the webhook. For example, if your webhook URL is https://mydomain.com/telegram, the certificate must recognize mydomain.com.

Do not rely on the default behavior of many development environments where the private key might be restricted or the certificate chain is incomplete. Telegram's validation process is strict; it will reject a connection if the certificate presented by your server does not match the hostname in the URL or if the signature cannot be verified against the public key.

Updating the Webhook Endpoint

Once you have successfully placed cert.pem and key.pem on your server (e.g., /var/www/mybot/cert.pem), you proceed to update the webhook. The command requires the url, allowed_updates, and crucially, the certificate parameter.

curl -X POST "https://api.telegram.org/bot<TOKEN>/setWebhook" \
     -H 'Content-Type: application/json' \
     --data-urlencode "url=https://mydomain.com/telegram" \
     --data-urlencode "allowed_updates=['message']" \
     --data-urlencode "certificate=@/path/to/cert.pem"

Notice the use of --data-urlencode for the certificate. This is required because the certificate is a binary file, but the API expects it as part of the multipart form data. The path provided in the command must be accessible to the process running the curl command or the script making the request.

Handling Local Development vs. Production

If you are testing locally without exposing your machine to the public internet via port 443, the self-signed certificate approach becomes unnecessarily complex due to firewall and routing constraints. In such scenarios, developers often temporarily use Telegram's cloud servers (https://api.telegram.org/bot<TOKEN>/setWebhook without a custom domain) or rely on tunneling services like ngrok.

However, ngrok presents its own set of complications. While ngrok provides an HTTPS endpoint with a valid certificate, it generates a new certificate for each session and may not allow you to pass the raw cert.pem file generated locally to the webhook update easily, as the handshake happens between Telegram and ngrok, not your local machine directly.

For production environments where you want full control over routing and SSL termination, hosting the bot on a VPS (like Ubuntu with Nginx or Apache) is the recommended path. In this setup, you would typically use Let's Encrypt to obtain a free, trusted public certificate. Using a publicly trusted CA eliminates the need for the certificate parameter entirely during the setWebhook call, simplifying the configuration significantly.

curl -X POST "https://api.telegram.org/bot<TOKEN>/setWebhook" \
     -H 'Content-Type: application/json' \
     --data-urlencode "url=https://mydomain.com/telegram" \
     -d '{"allowed_updates": ["message"]}'

When a trusted certificate is in place (handled by your web server via aiohttp, php-openssl, or equivalent), you omit the file upload. This reduces latency during the API call and avoids potential issues with file permissions on the server side.

Verification and Troubleshooting

After executing the webhook update, Telegram responds with a JSON object indicating success or failure. A common error is 400 Bad Request regarding the certificate, which usually points to a mismatch between the hostname in the URL and the certificate's CN/SAN, or an invalid key pair.

If you continue to encounter issues with self-signed certificates, consider whether the complexity of managing private keys and manual certificate uploads outweighs the benefits for your specific use case. For most production applications, integrating a trusted CA is a more robust solution that aligns with standard security practices without requiring special API parameters.

Our network