uptime-kuma-gchat-proxy

uptime-kuma-gchat-proxy is a lightweight webhook proxy service that converts Uptime Kuma notifications to Google Chat Card format. This middleware provides better preview and rich content display in mobile notifications.

---

Table of Contents

• Table of Contents
• Features
• Installation
• Configuration
• Usage
• API Endpoints
• Docker Deployment
• Systemd Deployment
• Troubleshooting
• Security
• Building
• License

---

Features

• 🚀 Lightweight and Fast - Written in Go for optimal performance
• 📱 Mobile Notification Preview - Enhanced preview support for mobile notifications
• 🎨 Rich Card Format - Beautiful Google Chat Card format with structured information
• 🐳 Docker Support - Easy deployment with Docker and Docker Compose
• 🔄 Auto Restart - Automatic restart on failure
• 💚 Health Check - Built-in health check endpoint for monitoring
• 🔒 Simple & Secure - Minimal dependencies and secure webhook handling

---

Installation

Method 1: Docker Compose (Recommended)

1. Create a .env file:

cp .env.example .env

2. Edit the .env file and add your Google Chat webhook URL:

GOOGLE_CHAT_WEBHOOK_URL=https://chat.googleapis.com/v1/spaces/XXXXX/messages?key=XXXXX&token=XXXXX

3. Start the service:

docker-compose up -d

Method 2: Docker

docker build -t uptime-kuma-gchat-proxy .
docker run -d \
  -p 8080:8080 \
  -e GOOGLE_CHAT_WEBHOOK_URL="your_webhook_url" \
  uptime-kuma-gchat-proxy

Method 3: Direct Go Execution

# Download dependencies
go mod download

# Set environment variable
export GOOGLE_CHAT_WEBHOOK_URL="your_webhook_url"

# Run the application
go run main.go

---

Configuration

Environment Variables

Variable	Description	Default	Required
GOOGLE_CHAT_WEBHOOK_URL	Default Google Chat webhook URL	-	Yes (if GOOGLE_CHAT_WEBHOOK_URLS is empty)
GOOGLE_CHAT_WEBHOOK_URLS	Comma-separated id=url pairs for multi-tenant routing	-	Yes (if GOOGLE_CHAT_WEBHOOK_URL is empty)
PORT	Port for the service to listen on	8080	No

Example multi-tenant mapping:

GOOGLE_CHAT_WEBHOOK_URLS=team-a=https://chat.googleapis.com/v1/spaces/AAA/messages?key=AAA&token=AAA,team-b=https://chat.googleapis.com/v1/spaces/BBB/messages?key=BBB&token=BBB

Getting Google Chat Webhook URL

1. Open a Space in Google Chat
2. Click the ▼ next to the Space name
3. Select Apps & integrations
4. Click Add webhook
5. Enter a name for the webhook (e.g., "Uptime Kuma")
6. Click Save
7. Copy the webhook URL

Uptime Kuma Configuration

1. Go to Settings > Notifications in Uptime Kuma
2. Click Setup Notification
3. Select Webhook as the Notification Type
4. Enter the following information:
   • Friendly Name: Google Chat (Proxy)
   • Post URL: http://localhost:8080/webhook (or http://localhost:8080/webhook/{identifier} for multi-tenant)
   • Content Type: application/json
5. Click Test to verify the connection
6. Click Save

---

Usage

Basic Usage

Once the service is running, configure Uptime Kuma to send webhooks to:

http://your-server:8080/webhook

Multi-tenant usage with an identifier:

http://your-server:8080/webhook/team-a

The proxy will automatically:

• Receive Uptime Kuma notifications
• Convert them to Google Chat Card format
• Forward them to your Google Chat Space

Card Format Features

The converted cards include:

• Status Indicator - 🟢 UP / 🔴 DOWN with emoji
• Monitor Name - Clear identification of the monitored service
• URL - Direct link to the monitored service
• Response Time - Ping/response time in milliseconds
• Timestamp - When the status change occurred
• Visit Button - Quick access button to visit the monitored site

Example Scenarios

Scenario 1: Local Docker Usage

# Set .env file
echo 'GOOGLE_CHAT_WEBHOOK_URL=your_webhook_url' > .env

# Start service
docker-compose up -d

# Configure Uptime Kuma webhook URL
# http://localhost:8080/webhook

Scenario 2: Server Deployment

# Start service
docker-compose up -d

# Configure Uptime Kuma webhook URL
# http://your-server-ip:8080/webhook

# Or with domain
# https://uptime-proxy.yourdomain.com/webhook

Scenario 3: Same Docker Network as Uptime Kuma

# In docker-compose.yml
services:
  uptime-kuma:
    # ...
    networks:
      - monitoring

  uptime-kuma-gchat-proxy:
    # ...
    networks:
      - monitoring

networks:
  monitoring:

Uptime Kuma webhook URL: http://uptime-kuma-gchat-proxy:8080/webhook

---

API Endpoints

POST /webhook

Receives webhooks from Uptime Kuma and forwards them to Google Chat.

POST /webhook/{identifier}

Receives webhooks and forwards them to the Google Chat webhook mapped to {identifier}.

Request Body:

{
  "heartbeat": {
    "monitorID": 1,
    "status": 1,
    "time": "2025-11-07 12:00:00",
    "msg": "OK",
    "ping": 123.45
  },
  "monitor": {
    "id": 1,
    "name": "My Website",
    "url": "https://example.com",
    "hostname": "example.com",
    "port": 443,
    "type": "http"
  },
  "msg": "Service is up"
}

Response:

200 OK

GET /health

Health check endpoint for monitoring the service status.

Response:

200 OK

---

Docker Deployment

Docker Compose

The included docker-compose.yml provides:

• Automatic restart on failure
• Health check configuration
• Port mapping
• Environment variable management

Docker Images

Build your own image:

docker build -t uptime-kuma-gchat-proxy .

Health Checks

The service includes a health check endpoint that can be used with Docker health checks:

healthcheck:
  test: ["CMD", "wget", "--no-verbose", "--tries=1", "--spider", "http://localhost:8080/health"]
  interval: 30s
  timeout: 10s
  retries: 3
  start_period: 40s

---

Systemd Deployment

This repository includes a sample unit file at systemd/uptime-kuma-gchat-proxy.service for running the proxy as a systemd service on Linux hosts.

1. Build or download the binary and place it in /usr/local/bin/uptime-kuma-gchat-proxy.

2. Create an environment file (e.g. /etc/uptime-kuma-gchat-proxy.env) that defines at least GOOGLE_CHAT_WEBHOOK_URL.

3. Copy the unit file into /etc/systemd/system/ and adjust User, Group, or paths as needed.

4. Reload systemd and enable the service:

   sudo systemctl daemon-reload
   sudo systemctl enable --now uptime-kuma-gchat-proxy.service

Check the status or logs with:

sudo systemctl status uptime-kuma-gchat-proxy.service
sudo journalctl -u uptime-kuma-gchat-proxy.service -f

---

Troubleshooting

Notifications Not Arriving

1. Check if the service is running:

   curl http://localhost:8080/health

2. Verify the webhook URL is correct in Uptime Kuma
3. Test the Google Chat webhook URL directly
4. Check logs:

   docker-compose logs -f uptime-kuma-gchat-proxy

No Preview in Mobile Notifications

• Verify that cards are being sent correctly (check logs)
• Ensure you're using a Google Chat Space (card preview may not work in DMs)
• Check that the webhook URL is valid and active

Port Conflict

Change the PORT environment variable in .env:

PORT=9090

Logging

View service logs:

# Docker logs
docker-compose logs -f uptime-kuma-gchat-proxy

# Filter errors only
docker-compose logs -f uptime-kuma-gchat-proxy | grep ERROR

---

Security

• Webhook URLs are sensitive - Keep them secure and never commit them to version control
• Use HTTPS in production - Always use HTTPS for production deployments
• Firewall rules - Restrict access to only necessary IPs
• Environment variables - Store sensitive data in environment variables, not in code
• Network isolation - Use Docker networks to isolate services when possible

---

Building

To build the application:

go build -o uptime-kuma-gchat-proxy main.go

Or using Docker:

docker build -t uptime-kuma-gchat-proxy .

---

License

This project is released under the GNU General Public License v3.0.

• You may run, study, share, and modify the software, provided derivative works remain GPL-compatible.
• Source code for any distributed binaries must be made available to recipients.
• The software is provided “as is”, without warranty; see LICENSE for the full text.