Webhook Configuration

Configure webhooks for production deployments of Alita Robot.

Webhook Configuration

Webhooks provide real-time message delivery from Telegram to your bot, making them ideal for production deployments. This guide covers the setup and configuration of webhooks for Alita Robot.

Polling vs Webhooks

Required Environment Variables

:::caution[Security] If WEBHOOK_SECRET is left empty, the webhook handler will reject ALL incoming requests. Always generate a strong random secret. :::

# Enable webhook mode
USE_WEBHOOKS=true

# Your public HTTPS domain (required)
WEBHOOK_DOMAIN=https://your-domain.com

# Webhook secret for request validation (required — if empty, all webhook requests are rejected)
WEBHOOK_SECRET=your-random-secret-string

# HTTP server port (default: 8080)
HTTP_PORT=8080

Unified HTTP Server

Alita Robot uses a single HTTP server for all endpoints:

:::danger When ENABLE_PPROF=true is set, additional debug endpoints are available at /debug/pprof/*. These expose Go runtime profiling data and should never be enabled in production without access controls. :::

All endpoints run on the port specified by HTTP_PORT (default: 8080).

Webhook URL Format

Telegram will send updates to:

{WEBHOOK_DOMAIN}/webhook

For example, if:

• WEBHOOK_DOMAIN=https://bot.example.com
• WEBHOOK_SECRET=abc123

The webhook URL will be: https://bot.example.com/webhook. Telegram sends the secret separately in the X-Telegram-Bot-Api-Secret-Token header.

Cloudflare Tunnel Setup

:::tip[Recommended] Cloudflare Tunnel is the recommended way to expose your bot to the internet. It handles SSL certificates automatically and does not require opening ports on your firewall. :::

Step 1: Install cloudflared

# macOS
brew install cloudflare/cloudflare/cloudflared

# Linux (Debian/Ubuntu)
curl -L https://pkg.cloudflare.com/cloudflare-main.gpg | sudo apt-key add -
echo "deb https://pkg.cloudflare.com/cloudflared $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/cloudflared.list
sudo apt update && sudo apt install cloudflared

# Docker
docker pull cloudflare/cloudflared

Step 2: Authenticate

cloudflared tunnel login

Step 3: Create a Tunnel

cloudflared tunnel create alita-bot

This creates a tunnel and outputs a tunnel ID.

Step 4: Configure DNS

cloudflared tunnel route dns alita-bot bot.yourdomain.com

Step 5: Create config.yml

tunnel: <your-tunnel-id>
credentials-file: /root/.cloudflared/<tunnel-id>.json

ingress:
  - hostname: bot.yourdomain.com
    service: http://localhost:8080
  - service: http_status:404

Step 6: Run the Tunnel

# Run in foreground
cloudflared tunnel run alita-bot

# Or install as a service
sudo cloudflared service install

Step 7: Configure Environment

WEBHOOK_DOMAIN=https://bot.yourdomain.com
WEBHOOK_SECRET=your-secure-random-string
USE_WEBHOOKS=true

Alternative: Cloudflare Tunnel Token

For Docker deployments, you can use a tunnel token instead:

# Generate token from Cloudflare dashboard
CLOUDFLARE_TUNNEL_TOKEN=your-tunnel-token

Add to docker-compose.yml:

services:
  cloudflared:
    image: cloudflare/cloudflared:latest
    restart: always
    command: tunnel --no-autoupdate run --token ${CLOUDFLARE_TUNNEL_TOKEN}
    depends_on:
      - alita

Security Best Practices

1. Always Set WEBHOOK_SECRET

The webhook secret is required for security. If left empty, the webhook handler will reject all incoming requests. Generate a secure value:

# Generate a secure random secret
openssl rand -hex 32

2. Validate Webhook Origin

Alita validates the X-Telegram-Bot-Api-Secret-Token header against WEBHOOK_SECRET before reading the request body. The secret is never placed in the URL.

3. Use HTTPS Only

:::caution Telegram requires HTTPS for webhooks. Never use HTTP in production. If you do not have an SSL certificate, use Cloudflare Tunnel or Let’s Encrypt. :::

4. Keep Your Secret Private

• Never commit WEBHOOK_SECRET to version control
• Use environment variables or secrets management
• Rotate the secret periodically

5. Monitor Webhook Health

Check the /health endpoint regularly:

curl https://bot.yourdomain.com/health

Nginx Reverse Proxy (Alternative)

If you prefer Nginx over Cloudflare Tunnel:

server {
    listen 443 ssl http2;
    server_name bot.yourdomain.com;

    ssl_certificate /etc/letsencrypt/live/bot.yourdomain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/bot.yourdomain.com/privkey.pem;

    location / {
        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;
    }
}

Switching Between Modes

From Polling to Webhook

1. Stop the bot
2. Set USE_WEBHOOKS=true and configure webhook variables
3. Start the bot (it will automatically register the webhook with Telegram)

From Webhook to Polling

1. Stop the bot
2. Set USE_WEBHOOKS=false or remove the variable
3. Start the bot (it will automatically delete the webhook)

The bot logs confirm the switch:

[Polling] Removed Webhook!
[Polling] Started Polling...!

or

[HTTPServer] Unified HTTP server started on port 8080 (health, metrics, webhook)

Troubleshooting

Webhook not receiving updates

1. Verify the domain is accessible:

   curl -I https://your-domain.com/health

2. Check Telegram webhook status:

   curl "https://api.telegram.org/bot<YOUR_TOKEN>/getWebhookInfo"

3. Ensure WEBHOOK_SECRET is configured correctly

401 Unauthorized errors

• Check that WEBHOOK_SECRET is correctly configured
• Verify the X-Telegram-Bot-Api-Secret-Token header matches your secret

Connection timeout

• Ensure port 8080 (or your HTTP_PORT) is accessible
• Check firewall rules
• Verify Cloudflare Tunnel or reverse proxy is running

SSL Certificate errors

• Use a valid SSL certificate (Let’s Encrypt is free)
• Cloudflare Tunnel handles SSL automatically