A production-ready webhook relay that transforms Fizzy notifications into Telegram messages using Clean Architecture principles.

Telefizz listens for webhook events from Fizzy and instantly relays them to Telegram. Built with Clean Architecture for maintainability, it's designed to be self-hosted, scalable, and easy to understand.

Perfect for teams that want real-time Fizzy notifications without context-switching.

✨ Real-time Notifications - Instant Telegram alerts for Fizzy events
🔒 Secure - HMAC-SHA256 signature verification for webhook authenticity
🏗️ Clean Architecture - Well-organized, testable, and maintainable codebase
🐳 Containerized - Production-ready Docker setup with Kamal deployment
🚀 Zero-Downtime Deploys - Automatic rolling updates via Kamal
✅ Health Checks - Built-in /up endpoint for monitoring

• 📌 Card Published
• 📋 Card Board Changed
• 💬 Comment Created
• 👤 Card Assigned / Unassigned
• 🏷️ Card Triaged
• ✅ Card Closed / Reopened
• ⏸️ Card Postponed
• 🔄 Card Sent Back to Triage

1. Clone and install dependencies:

   git clone <repository>
   cd telefizz
   bundle install

2. Configure environment variables:

   cp .env.example .env

   Edit .env with your credentials:

   TELEGRAM_BOT_TOKEN=your_bot_token_here
   TELEGRAM_CHAT_ID=your_chat_id_here
   FIZZY_WEBHOOK_SECRET=your_webhook_secret_here

3. Run the application:

   ruby app.rb

   The app will be available at http://localhost:9292

4. Run tests:

   bundle exec rake test

Telefizz is production-ready with Kamal, a zero-downtime deployment tool for containerized applications.

• Docker installed on your deployment server
• SSH access to your server
• A domain name with DNS pointing to your server

1. Install Kamal:

   gem install kamal

2. Configure deployment:

   Edit config/deploy.yml:

   • Update servers.web with your server IP (or set SERVER_IP in .env)
   • Update proxy.host with your domain (or set APP_HOST in .env)
   • Configure registry credentials if using a private registry

3. Create .env file with your secrets:

   cp .env.example .env
   # Edit .env with actual values

   💡 Tip: We recommend using the dotenv gem for to easily handle your credentials. Install it globally and use dotenv kamal setup instead of kamal setup to automatically load your .env file. Of course, you can also use a Password Manager as per Kamals Documentation.

4. Deploy:

   # With dotenv
   dotenv kamal setup     # First-time setup
   dotenv kamal deploy    # Deploy your app
   
   # Or without dotenv
   kamal setup
   kamal deploy

# View deployment status
kamal status

# View container logs
kamal logs

# Execute a command in the container
kamal app exec "command"

# Rollback to previous version
kamal rollback

# Stop the application
kamal stop

# Start the application
kamal start

# Redeploy current version
kamal redeploy

Kamal automatically provisions free SSL certificates via Let's Encrypt. Update config/deploy.yml:

proxy:
  ssl: true
  host: your-domain.com

Telefizz follows Clean Architecture principles for maximum maintainability:

lib/
├── entities/              # Domain objects
│   ├── event.rb          # Webhook event representation
│   └── message.rb        # Telegram message representation
├── use_cases/            # Business logic
│   └── process_webhook_event.rb
├── interfaces/           # Controllers and gateways
│   ├── webhook_controller.rb
│   └── gateways/
│       └── message_gateway.rb
└── infrastructure/       # External services
    └── telegram_message_gateway.rb

• Entities: Pure domain objects with no external dependencies
• Use Cases: Application business logic, independent of delivery mechanism
• Interfaces: Controllers (HTTP handlers) and gateway interfaces
• Infrastructure: Concrete implementations of external integrations (Telegram API)

This structure allows you to:

• Test business logic without HTTP or external service mocking
• Easily swap implementations (e.g., different notification services)
• Understand the codebase at a glance

bundle exec rake test

telefizz/
├── app.rb                 # Sinatra application entry point
├── config.ru              # Rack configuration
├── Gemfile               # Ruby dependencies
├── Gemfile.lock          # Locked dependency versions
├── Dockerfile            # Production container definition
├── config/
│   └── deploy.yml        # Kamal deployment configuration
├── lib/                  # Application code
└── test/                 # Test files

See config/deploy.yml for all available options. Key settings:

• servers.web: Your deployment server(s)
• proxy.host: Your domain name
• proxy.ssl: Enable HTTPS (default: true)
• env.secret: Environment variables to inject into containers

The /up endpoint provides a health check for monitoring solutions:

curl https://your-domain.com/up
# Returns: 200 OK

Use this with Kamal's health checks, monitoring services, or load balancers to ensure your app stays running.

• ✅ Webhook signatures verified via HMAC-SHA256
• ✅ Runs as non-root user in container
• ✅ Environment secrets never committed to git
• ✅ SSL/TLS encryption enabled by default

1. Verify FIZZY_WEBHOOK_SECRET matches your Fizzy webhook configuration
2. Check logs: kamal logs
3. Test webhook manually with cURL

Kamal automatically handles Let's Encrypt certificates. If issues persist:

kamal redeploy  # Restart to refresh certificates

Contributions are welcome! Please feel free to submit a Pull Request.

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

For issues, questions, or suggestions, please open an issue on GitHub.

Made with ❤️ for real-time notifications