---
title: Webhook Configuration
description: 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

| Feature | Polling | Webhooks |
|---------|---------|----------|
| **Latency** | 1-3 seconds | Instant (~50ms) |
| **Setup Complexity** | Simple | Requires HTTPS |
| **Resource Usage** | Higher (constant requests) | Lower (on-demand) |
| **Network** | Works behind NAT | Requires public endpoint |
| **Use Case** | Development, testing | Production |
| **External Dependencies** | None | Reverse proxy or tunnel |

## Required Environment Variables

:::caution[Security]
With `USE_WEBHOOKS=true`, the bot refuses to start if `WEBHOOK_SECRET` (or `WEBHOOK_DOMAIN`) is empty: it exits with a configuration error such as `WEBHOOK_SECRET is required when USE_WEBHOOKS is enabled for security`. Always generate a strong random secret.
:::

```bash
# Enable webhook mode
USE_WEBHOOKS=true

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

# Webhook secret for request validation (required — the bot exits at startup if it is empty)
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:

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/health` | GET | Health check with database and Redis status |
| `/metrics` | GET | Prometheus metrics for monitoring |
| `/db_metrics` | GET | Database connection pool statistics (requires `Authorization: Bearer <METRICS_AUTH_TOKEN>` when that variable is set) |
| `/webhook` | POST | Telegram webhook endpoint (webhook mode only) |
| `/debug/pprof/*` | GET | Go profiling endpoints (only when `ENABLE_PPROF=true`) |

:::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

```bash
# 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

```bash
cloudflared tunnel login
```

### Step 3: Create a Tunnel

```bash
cloudflared tunnel create alita-bot
```

This creates a tunnel and outputs a tunnel ID.

### Step 4: Configure DNS

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

### Step 5: Create config.yml

```yaml
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

```bash
# Run in foreground
cloudflared tunnel run alita-bot

# Or install as a service
sudo cloudflared service install
```

### Step 7: Configure Environment

```bash
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:

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

Add to docker-compose.yml:

```yaml
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 it is empty while `USE_WEBHOOKS=true`, the bot exits at startup with a configuration error. Generate a secure value:

```bash
# 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:

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

## Nginx Reverse Proxy (Alternative)

If you prefer Nginx over Cloudflare Tunnel:

```nginx
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:
   ```bash
   curl -I https://your-domain.com/health
   ```

2. Check Telegram webhook status:
   ```bash
   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