A webhook bot that sends instant Telegram notifications whenever you receive a payment through GitHub Sponsors. Get real-time alerts with complete transaction details directly to your Telegram account.

📋 Table of Contents

Features
Prerequisites
Installation
- Option 1: Docker Installation
- Option 2: Manual Installation
Configuration
Usage
- Running the Bot
- Testing the Webhook
Deployment
- Local Deployment
- Cloud Deployment
Architecture
Troubleshooting
Performance Optimization
Contributing
License

🚀 Features

Real-time Notifications: Receive immediate alerts when someone sponsors you on GitHub
Complete Transaction Details: Get sponsor name, amount, tier selected, and timestamp
Secure Webhook Integration: Verify webhook signatures for secure communication
Single-File Design: All functionality in one Python file for simplicity
Docker Support: Easy deployment with Docker
Customizable: Configure to meet your specific needs
Lightweight: Minimal resource requirements
Open Source: MIT licensed, free to use and modify

📋 Prerequisites

Before you begin, ensure you have the following:

Python 3.7 or higher
A GitHub account with Sponsors enabled
A Telegram account
A publicly accessible server to receive webhooks (or use a service like ngrok for testing)
Docker (optional, for containerized deployment)

🔧 Installation

Option 1: Docker Installation

The easiest way to get started is using Docker:

Clone this repository:

git clone https://github.com/overspend1/github-sponsors-webhook-bot.git
cd github-sponsors-webhook-bot

Create a .env file based on the example:
```
cp .env.example .env
```
Edit the .env file with your credentials (see Configuration section)

Build and run the Docker container:

docker build -t github-sponsors-bot .
docker run -d -p 5000:5000 --name sponsors-bot --env-file .env github-sponsors-bot

Option 2: Manual Installation

If you prefer to run the bot without Docker:

Clone this repository:

git clone https://github.com/overspend1/github-sponsors-webhook-bot.git
cd github-sponsors-webhook-bot

Create a virtual environment:

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

Install dependencies:
```
pip install -r requirements.txt
```
Create a .env file based on the example:
```
cp .env.example .env
```
Edit the .env file with your credentials (see Configuration section)
Run the bot:
```
python github_sponsors_bot.py
```

⚙️ Configuration

Environment Variables

The bot requires the following environment variables to be set in your .env file:

Variable	Description	Example
`GITHUB_WEBHOOK_SECRET`	Secret for verifying GitHub webhook signatures	`your_webhook_secret`
`TELEGRAM_TOKEN`	Telegram Bot API token	`1234567890:ABCDEFGHIJKLMNOPQRSTUVWXYZ`
`TELEGRAM_CHAT_ID`	Telegram chat ID to send notifications to	`123456789`
`WEBHOOK_HOST`	Host to bind the webhook server to (optional)	`0.0.0.0`
`WEBHOOK_PORT`	Port to bind the webhook server to (optional)	`5000`

GitHub Webhook Setup

Go to your GitHub repository or organization settings
Navigate to "Webhooks" and click "Add webhook"
For the Payload URL, enter your server URL (e.g., https://your-server.com/webhook/github)
Set Content type to application/json
Generate a secure random string to use as your webhook secret:
```
openssl rand -hex 20
```
Enter this secret in the "Secret" field and in your .env file
Under "Which events would you like to trigger this webhook?", select "Let me select individual events"
Check only the "Sponsorships" option
Ensure "Active" is checked and click "Add webhook"

Telegram Bot Setup

Open Telegram and search for @BotFather
Send the command /newbot and follow the instructions
BotFather will provide you with a token (copy this to your .env file)
Start a chat with your new bot by clicking the link provided by BotFather
To get your chat ID, start a chat with @userinfobot
The bot will reply with your account information, including your Chat ID
Copy this Chat ID to your .env file

🎮 Usage

Running the Bot

Once configured, the bot will:

Start a webhook server listening for GitHub events
Initialize the Telegram bot
Send a startup message to your Telegram chat
Process incoming webhook events and send notifications

The bot logs its activity to both the console and a log file (github_sponsors_bot.log).

Testing the Webhook

You can test the webhook integration without setting up a real GitHub webhook by using the included test script:

python test_webhook.py

This will send a simulated GitHub Sponsors webhook event to your local server. If everything is set up correctly, you should receive a notification in your Telegram chat.

For testing with a real GitHub webhook but without exposing your local server to the internet, you can use ngrok:

ngrok http 5000

Then update your GitHub webhook URL with the ngrok URL (e.g., https://a1b2c3d4.ngrok.io/webhook/github).

🚢 Deployment

Local Deployment

For local development or personal use, you can run the bot directly on your machine:

python github_sponsors_bot.py

To keep the bot running after you close your terminal, you can use tools like:

nohup on Linux/macOS:
```
nohup python github_sponsors_bot.py &
```

screen or tmux for terminal sessions:

screen -S sponsors-bot
python github_sponsors_bot.py
# Press Ctrl+A, D to detach

Windows Task Scheduler for Windows systems

Cloud Deployment

For production use, we recommend deploying to a cloud provider:

Heroku

Install the Heroku CLI

heroku login
heroku create your-app-name

Set environment variables:

heroku config:set GITHUB_WEBHOOK_SECRET=your_secret
heroku config:set TELEGRAM_TOKEN=your_telegram_token
heroku config:set TELEGRAM_CHAT_ID=your_chat_id

Deploy the app:
```
git push heroku main
```
Update your GitHub webhook URL to https://your-app-name.herokuapp.com/webhook/github

AWS

Create an EC2 instance
Install Docker on the instance
Clone the repository and build the Docker image
Run the container with your environment variables
Set up a load balancer or Elastic IP for a stable endpoint
Update your GitHub webhook URL with your instance's public address

Digital Ocean

Create a Droplet
Install Docker on the Droplet
Clone the repository and build the Docker image
Run the container with your environment variables
Set up a Floating IP for a stable endpoint
Update your GitHub webhook URL with your Droplet's public address

🏗️ Architecture

The bot is designed with a simple, single-file architecture for ease of understanding and maintenance. For more details on the architecture, see ARCHITECTURE.md.

Key components:

Flask Web Server: Handles incoming webhook requests
Webhook Handler: Verifies and processes GitHub webhook events
Telegram Bot: Sends notifications to your Telegram chat

🔍 Troubleshooting

Common Issues

Webhook Not Receiving Events

Problem: GitHub webhook events aren't being received by your server.
Solutions:
- Verify your server is publicly accessible
- Check that the webhook URL in GitHub settings is correct
- Ensure your server is running and listening on the correct port
- Check firewall settings to allow incoming connections
- Look at GitHub webhook delivery logs for error details

Invalid Signature Errors

Problem: Webhook requests are being rejected due to invalid signatures.
Solutions:
- Verify the webhook secret in your .env file matches the one in GitHub settings
- Ensure the webhook payload is not being modified in transit (use HTTPS)
- Check that the content type is set to application/json in GitHub webhook settings

Telegram Bot Not Sending Messages

Problem: Notifications aren't being sent to Telegram.
Solutions:
- Confirm your bot token is correct
- Ensure you've started a conversation with your bot
- Verify your chat ID is correct
- Check if the bot has been blocked or deleted
- Look at the bot logs for error messages

Docker Container Issues

Problem: Docker container won't start or crashes.
Solutions:
- Check Docker logs: docker logs sponsors-bot
- Verify environment variables are set correctly
- Ensure the required ports are available
- Check for permission issues

Debugging

To enable more detailed logging, you can modify the logging level in github_sponsors_bot.py:

logging.basicConfig(
    level=logging.DEBUG,  # Change from INFO to DEBUG
    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
    handlers=[
        logging.StreamHandler(),
        logging.FileHandler('github_sponsors_bot.log')
    ]
)

⚡ Performance Optimization

For optimal performance:

Use HTTPS: Always use HTTPS for your webhook endpoint to ensure secure communication.
Minimize Response Time: The webhook handler should process events quickly to avoid timeouts.
Use a Production WSGI Server: For production deployments, use Gunicorn (included in the Docker setup) or uWSGI instead of Flask's development server.
Monitor Resource Usage: Keep an eye on CPU and memory usage, especially for high-traffic repositories.
Implement Rate Limiting: If you expect a high volume of sponsorships, consider implementing rate limiting for Telegram notifications.
Use a Reverse Proxy: For production deployments, use Nginx or Apache as a reverse proxy in front of the application.

🤝 Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.