slack-to-ntfy/README.md

Slack to ntfy Middleware

A lightweight Go service that acts as a middleware between Slack webhooks and ntfy servers, with Bearer token authentication and basic authentication support.

Features

• ✅ Parses Slack webhook format
• ✅ Forwards alerts to self-hosted ntfy servers
• ✅ Bearer token authentication support
• ✅ Health check endpoint
• ✅ Lightweight Docker container (~8.4MB)
• ✅ High performance and low resource usage

Quick Start

1. Configure the service:

   # Edit docker-compose.yml and set:
   # - NTFY_BASE_URL=https://your-ntfy-server.com
   # - NTFY_TOKEN=tk_your_bearer_token
   # OR
   # - NTFY_USERNAME=your_username
   # - NTFY_PASSWORD=your_password
   

2. Run the service:

   docker compose up -d
   

3. Configure Slack:

   • Go to Slack Integrations → Incoming Webhooks
   • Add new webhook
   • Webhook URL: https://your-server-ip:8080/your-topic-name

4. Test the service:

   # Test webhook with HTTP (if TLS is disabled)
   curl -X POST https://localhost:8080/test-topic \
        -H 'Content-Type: application/json' \
        -d '{"text": "Test alert from Slack to ntfy"}'
   
   # Test webhook with HTTPS (if TLS is enabled, and if using self-signed certs, add -k or --insecure)
   curl -k -X POST https://localhost:8080/test-topic -k \
        -H 'Content-Type: application/json' \
        -d '{"text": "Test alert from Slack to ntfy (TLS)"}'
   
   # Check health with HTTP (if TLS is disabled)
   curl http://localhost:8080/health
   
   # Check health with HTTPS (if TLS is enabled, and if using self-signed certs, add -k or --insecure)
   curl https://localhost:8080/health -k
   

Configuration

Environment Variable	Default	Description
NTFY_BASE_URL	https://ntfy.sh	Your ntfy server URL (without topic)
NTFY_TOKEN	""	Bearer token for ntfy authentication
NTFY_USERNAME	""	Username for ntfy basic authentication
NTFY_PASSWORD	""	Password for ntfy basic authentication
BIND_ADDRESS	0.0.0.0	Interface to bind to
BIND_PORT	8080	Port to listen on
TLS_CERT_FILE	""	Path to TLS certificate file (e.g., /app/certs/server.crt)
TLS_KEY_FILE	""	Path to TLS private key file (e.g., /app/certs/server.key)

Enabling TLS

TLS is enabled by default. If TLS_CERT_FILE and TLS_KEY_FILE environment variables are not set, a self-signed certificate and key will be automatically generated on startup.

To provide your own certificate and key files (optional):

1. Create a certs directory in the root of your project:

   mkdir certs
   # Copy your server.crt and server.key into the certs/ directory
   

2. Uncomment and set TLS_CERT_FILE and TLS_KEY_FILE in your docker-compose.yml (e.g., pointing to /app/certs/server.crt and /app/certs/server.key):

   environment:
     # ... existing environment variables ...
     - TLS_CERT_FILE=/app/certs/server.crt
     - TLS_KEY_FILE=/app/certs/server.key
   

3. Ensure the volumes section is uncommented and correctly mounts the certs directory:

   volumes:
     - ./certs:/app/certs
   

Important: Regardless of whether you use generated or custom certificates:

• Update your Slack webhook URL to use https.
• Restart your Docker service:

  docker compose down
  docker compose up -d
  

• When testing with curl against a self-signed certificate, you may need to add the -k or --insecure flag to bypass certificate validation.
• Exposing on standard HTTPS port (443) in production: While the service runs on port 8080 internally, it's common to map it to port 443 externally (e.g., - "443:8080" in docker-compose.yml) or use a reverse proxy to handle TLS termination on port 443 and forward traffic to the container's port 8080.

Development

Build locally

make build
make run

Build Docker image

make docker-build

Run tests

make test

License

MIT License