Watchful protector of your services
Heimdall - A lightweight, high-performance service monitoring tool that continuously checks your services' health and sends instant notifications when they become unavailable.
- π Continuous Monitoring: Real-time health checks with configurable intervals
- π± Multi-Platform Notifications: Instant alerts via Telegram, Discord, Slack, or custom webhook
- β‘ High Performance: Lightweight Go implementation with minimal resource usage
- π― Flexible Configuration: Support for both strict and lenient health checks
- π Zero Dependencies: No external dependencies - only Go standard library
- Go 1.24.2 or higher
- Telegram Bot Token (for Telegram notifications)
- Discord Webhook URL (for Discord notifications)
- Slack Bot Token (for Slack notifications)
-
Clone the repository
git clone https://github.com/MowlCoder/heimdall.git cd heimdall
-
Build the application
# Using Task (recommended) task build # Or using Go directly go build -o bin/heimdall ./cmd/heimdall/main.go
-
Create configuration file
cp config.example.json config.json
-
Configure your services and notifiers
{ "services": [ { "name": "My Website", "url": "https://example.com", "interval": "30s", "strict": true, "headers": { "User-Agent": "Heimdall-Monitor/1.0", "Authorization": "Bearer your-token" } }, { "name": "API Service", "url": "https://api.example.com/health", "interval": "1m", "strict": false, "timeout": 5000 } ], "notifiers": { "telegram": { "chatId": "YOUR_CHAT_ID", "botToken": "YOUR_BOT_TOKEN", "enabled": true }, "discord": { "webhook": "YOUR_DISCORD_WEBHOOK_URL", "enabled": false }, "slack": { "chatId": "YOUR_CHANNEL_ID", "botToken": "YOUR_SLACK_BOT_TOKEN", "enabled": true }, "webhook": { "webhook": "YOUR_CUSTOM_WEBHOOK_URL", "enabled": false } } }
-
Run the service
# Using Task task run # Or directly ./bin/heimdall --config ./config.json
Each service in the services
array supports the following parameters:
Parameter | Type | Required | Description | Example |
---|---|---|---|---|
name |
string | β | Human-readable service name | "My API" |
url |
string | β | Service URL to monitor | "https://api.example.com" |
interval |
string | β | Check interval (supports Go duration or milliseconds) | "30s" , "1m" , "30000" |
strict |
boolean | β | Strict mode (only 200 OK considered healthy) | true |
timeout |
integer | β | Request timeout in milliseconds | 600 |
headers |
object | β | Custom HTTP headers to send with requests | {"Authorization": "Bearer token"} |
Parameter | Type | Required | Description |
---|---|---|---|
chatId |
string | β | Telegram chat ID where notifications will be sent |
botToken |
string | β | Telegram bot token from @BotFather |
enabled |
boolean | β | Enable/disable Telegram notifications (default: true ) |
Parameter | Type | Required | Description |
---|---|---|---|
webhook |
string | β | Discord webhook URL for the channel |
enabled |
boolean | β | Enable/disable Discord notifications (default: true ) |
Parameter | Type | Required | Description |
---|---|---|---|
chatId |
string | β | Slack channel ID where notifications will be sent |
botToken |
string | β | Slack bot token |
enabled |
boolean | β | Enable/disable Slack notifications (default: true ) |
Parameter | Type | Required | Description |
---|---|---|---|
webhook |
string | β | Custom webhook URL where notifications will be sent |
enabled |
boolean | β | Enable/disable custom webhook notifications (default: true ) |
Webhook Payload Structure:
{
"name": "Service Name",
"statusCode": 500,
"body": "Error response body",
"error": "Error message"
}
- Only HTTP 200 status code is considered healthy
- Any other status code triggers a notification
- Ideal for APIs that should always return 200 OK
- HTTP 200-499 status codes are considered healthy
- Only 5xx server errors trigger notifications
- Suitable for services that may return redirects or client errors
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature
) - Commit your changes (
git commit -m 'Add amazing feature'
) - Push to the branch (
git push origin feature/amazing-feature
) - Open a Pull Request
This project is licensed under the MIT License - see the LICENSE file for details.
- Named after Heimdall, the Norse god who watches over the BifrΓΆst bridge
- Built with Go for performance and reliability
- Telegram Bot API, Discord Webhooks, Slack API, and custom webhooks for instant notifications
- Rich message formatting with emojis, timestamps, and structured information
Made with β€οΈ for reliable service monitoring