How to Debug a Telegram Bot Webhook Not Working

When a Telegram bot stops responding to webhook updates, the issue is almost always a mismatch in SSL certificates, unsupported ports, firewall blocks, or unhandled 500 errors on your application server. Follow this step-by-step technical guide to isolate and resolve the issue.

Step 1: Inspect the Webhook Status

The fastest way to diagnose webhook issues is by querying Telegram's API for your bot's current status. Send a GET request to the following URL in your browser or via cURL:

https://api.telegram.org/bot<YOUR_BOT_TOKEN>/getWebhookInfo

Analyze the JSON response payload. Look for these critical fields:

• has_custom_certificate: If true, ensure you uploaded the correct public key certificate.
• pending_update_count: A value greater than 0 indicates Telegram is trying to send updates, but your server is not responding correctly.
• last_error_date: The timestamp of the last failed delivery attempt.
• last_error_message: The exact reason for the failure (e.g., "SSL error", "Connection refused", "Timeout").

Step 2: Verify SSL/TLS Requirements

Telegram requires a secure HTTPS connection. Common SSL pitfalls include:

• Self-Signed Certificates: If using a self-signed certificate, you must upload your public key certificate (PEM format) when calling setWebhook.
• Missing Intermediate Certificates: If using a free CA like Let's Encrypt, ensure your server configuration includes the full certificate chain (usually fullchain.pem), not just the leaf certificate.
• TLS Version: Ensure your server supports TLS 1.2 or TLS 1.3. Older versions (TLS 1.0/1.1) are rejected by Telegram.

Step 3: Confirm Port and IP Restrictions

Telegram only sends webhook requests to specific ports. If your server is listening on an unsupported port, the connection will fail.

• Supported Ports: You must configure your server to listen on port 443, 80, 88, or 8443. Any other port will be ignored.
• IP Whitelisting: If your server is behind a firewall, you must allow incoming traffic from Telegram's subnet ranges: 149.154.160.0/20 and 91.108.4.0/22.

Step 4: Manually Simulate the Webhook Request

Isolate your server from Telegram by sending a mock update payload using cURL. This verifies if your application logic or routing is broken.

curl -X POST "https://yourdomain.com/your-webhook-path" \
-H "Content-Type: application/json" \
-d '{
  "update_id": 10000,
  "message": {
    "message_id": 1,
    "from": {
      "id": 12345,
      "is_bot": false,
      "first_name": "Test"
    },
    "chat": {
      "id": 12345,
      "type": "private"
    },
    "text": "/start"
  }
}'

Your server must return an HTTP status code of 200 OK. If it returns 500 Internal Server Error, 403 Forbidden, or redirects (301/302), Telegram will back off and temporarily stop sending updates.

Step 5: Reset the Webhook Connection

If you have resolved server-side issues but updates are still blocked, clear the pending queue by deleting and re-registering the webhook:

# Step A: Delete webhook and drop pending updates
https://api.telegram.org/bot<YOUR_BOT_TOKEN>/deleteWebhook?drop_pending_updates=true

# Step B: Re-set the webhook
https://api.telegram.org/bot<YOUR_BOT_TOKEN>/setWebhook?url=https://yourdomain.com/your-webhook-path

Setting drop_pending_updates=true discards old, failed updates, allowing your bot to start processing new messages instantly.

Need this done fast? order a fix on Kwork.