Sends Tailscale events to Telegram using Cloudflare Workers

Tailscale natively supports Slack, Discord, Google Chat, and Mattermost—but not Telegram.

TailHoogram bridges that gap with secure webhook processing, sending the event to Telegram. Can be deployed on Cloudflare Workers, even with the free tier.

Prerequisites: Python 3.12+, uv, Tailscale account, Telegram bot token

# Install
uv sync --extra dev

# Configure (.env file)
TAILSCALE_WEBHOOK_SECRET=your-secret
TELEGRAM_BOT_TOKEN=your-bot-token
TELEGRAM_CHAT_ID=your-chat-id

# Run locally with pywrangler
uv run pywrangler dev

# Deploy to Cloudflare Workers
uv run pywrangler secret put TAILSCALE_WEBHOOK_SECRET
uv run pywrangler secret put TELEGRAM_BOT_TOKEN
uv run pywrangler secret put TELEGRAM_CHAT_ID
uv run pywrangler deploy

Note: If you use linux secret service, namely secret-tool, you can skip the .env file step and use secret-tool-run to automatically load secrets from your vault.

# Run with secrets from vault
secret-tool-run uv run pywrangler dev

Tailscale Setup:

1. Go to Tailscale admin → Webhooks
2. Create webhook pointing to https://your-domain/events
3. Copy the secret and set as TAILSCALE_WEBHOOK_SECRET
4. Hit "Test" to verify

Test your webhook endpoint locally using the included test script:

# Test default endpoint (localhost:8000)
python test-endpoint.py

# Test custom endpoint
python test-endpoint.py --endpoint example.com:8080

The script automatically loads TAILSCALE_WEBHOOK_SECRET from your .env file and sends a properly signed test webhook.

• HMAC-SHA256 signature verification on every webhook
• Replay protection (5-minute timestamp window)
• Firewall recommendation: Restrict to Tailscale IP ranges (docs)

🔔 Tailscale Event

Type: policyUpdate
Tailnet: hugo-tailscale
Message: Tailnet policy file updated
Time: 2026-02-15T09:33:14.089607+00:00

Details:
  url: https://login.tailscale.com/admin/acls
  actor: hugobatista

This project includes a VSCode Dev Container configuration for easy local development. It sets up a consistent environment with all dependencies installed.

If you encounter permission issues with the dev container, you may need to adjust your SELinux policies, by relabeling the project directory with s0 and container_file_t contexts:

sudo chcon -Rt container_file_t -l s0 ./tailhoogram
# this command recursively changes the context of all files in the project directory to be accessible by the container

To restore the original context after development, you can use:

sudo restorecon -RvF ./tailhoogram
# this command recursively restores the default SELinux context for all files in the project directory