🚀 GitHub to Telegram Webhook Notifier

Get instant Telegram notifications for your private GitHub repository commits!

Never miss a commit again. This lightweight webhook server bridges GitHub push events directly to your Telegram chat with beautifully formatted notifications.

✨ Features

• 🔔 Instant notifications for every push to your repo
• 📝 Rich commit details including author, message, and direct links
• 🔐 Secure webhook verification with HMAC signatures
• 🎨 Beautiful Markdown formatting in Telegram messages
• 🚀 Lightweight & fast Flask-based server
• 🔧 Easy setup with environment variables

📸 Preview

When someone pushes to your repo, you'll get a notification like this:

🔄 New Push to my-awesome-repo

📁 Repository: my-awesome-repo
🌿 Branch: main
👤 Pushed by: mars
📝 Commits: 2

• a1b2c3d Fix authentication bug - mars
• e4f5g6h Add new feature endpoint - mars

🛠️ Quick Setup

1. Create Your Telegram Bot

1. Message @BotFather on Telegram
2. Send /newbot and follow the prompts
3. Save your bot token and username
4. Start a chat with your bot and send any message

2. Clone & Install

git clone <your-repo>
cd github-telegram-webhook
pip install -r requirements.txt

3. Configure Environment

Copy and customize the environment file:

cp .env.example .env

Edit .env with your details:

GITHUB_WEBHOOK_SECRET=your_super_secret_key_here
TELEGRAM_BOT_TOKEN=1234567890:ABCdefGHIjklMNOpqrsTUVwxyz
TELEGRAM_BOT_USERNAME=YourBotUsername
TELEGRAM_CHAT_ID=123456789
PORT=5000

4. Run the Server

# Development
python main.py

# Production (recommended)
pip install waitress
waitress-serve --host=0.0.0.0 --port=5000 webhook_server:app

5. Configure GitHub Webhook

1. Go to your repo → Settings → Webhooks → Add webhook
2. Payload URL: http://your-server-domain-or-ip.com:5000/webhook
3. Content type: application/json
4. Secret: Same as your GITHUB_WEBHOOK_SECRET
5. Events: Select "Just the push event"
6. ✅ Active

🔧 Configuration

Variable	Description	Required	Example
GITHUB_WEBHOOK_SECRET	Secret key for webhook verification	✅	my_super_secret_123
TELEGRAM_BOT_TOKEN	Your bot token from BotFather	✅	1234567890:ABC...
TELEGRAM_BOT_USERNAME	Your bot's username (optional)	❌	MyAwesomeBot
TELEGRAM_CHAT_ID	Your chat ID for notifications	✅	123456789
PORT	Server port	❌	5000

🔍 Testing

Test your webhook locally:

# Health check
curl http://localhost:5000/health

🔧 Troubleshooting

🚫 Webhook not receiving requests

1. Check if your server is accessible: curl http://your-server:port/health
2. Verify firewall settings: sudo ufw status
3. Check GitHub webhook delivery logs in repo settings
4. Ensure webhook URL is correct and includes /webhook path

📱 Not receiving Telegram messages

1. Verify bot token: curl https://api.telegram.org/bot<TOKEN>/getMe
2. Check chat ID: curl https://api.telegram.org/bot<TOKEN>/getUpdates
3. Ensure you've started a chat with your bot
4. Check server logs for error messages

🔐 Signature verification failed

1. Ensure GITHUB_WEBHOOK_SECRET matches webhook secret in GitHub
2. Check that content-type is application/json
3. Verify webhook is sending to correct endpoint

📄 License

MIT License - feel free to use this for your projects!

---

Made with ❤️ for developers who love staying updated

⭐ Star this repo if it helped you!