How bonzonkim/vmalert-webhook works
Project type and purpose
• This is a single-purpose backend microservice written in Go.
• It receives webhook calls from Vmalert, queries VictoriaLogs for log details, and forwards formatted alerts to Slack.
• It is containerized (Docker) and deployed on Kubernetes.
File structure
Top-level folders:
• .github/workflows – CI pipeline definition (ci.yaml)
• kubernetes – Deployment and Service YAMLs for the webhook in-cluster
• src – All Go source, Dockerfile, env setup, test scripts
– main.go – Entry point, HTTP server exposing /webhook
– types/type.go – Data models for Vmalert payload and VictoriaLogs responses
– util/util.go – HTTP clients, common helpers (env reading, JSON marshalling)
– vlog/vlog.go – VictoriaLogs query builder and execution
– webhook/webhook.go – Core business logic: parse alert, call vlog, construct Slack payload, push to Slack
– Dockerfile – Container build instructions
– test.sh – Local test script to simulate an alert
Key points from README
• Expects environment variables: VICTORIALOGS_ENDPOINT, SLACK_ENDPOINT, optional VLOG_INGRESS
• Usage: go run . locally or docker build + kubectl apply with updated env in webhook-deployment.yaml
• Integration: configured as a webhook receiver in Prometheus Alertmanager
Components
1. Vmalert (Prometheus Vmalert) – emits alerts via HTTP POST to /webhook
2. Webhook Microservice (vmalert-webhook)
• HTTP server (main.go)
• Business logic layer (webhook.go)
• VictoriaLogs client (vlog.go)
• Utilities & types (util.go, type.go)
3. VictoriaLogs – external time-series + log service
4. Slack Incoming Webhook – external messaging endpoint
5. Kubernetes Cluster – Deployment + Service (kubernetes/webhook-*.yaml)
6. CI Pipeline – GitHub Actions for building, testing, pushing container
b. Relationships & Data Flow
1. Vmalert → (POST /webhook) → Webhook Microservice
2. Webhook Microservice → (HTTP query) → VictoriaLogs endpoint
3. VictoriaLogs → (JSON response) → Webhook Microservice
4. Webhook Microservice → (POST message) → Slack endpoint
5. Docker build pipeline from src/Dockerfile → Container Registry → Kubernetes Deployment
6. GitHub Actions CI triggers on push → build → test → push image
c. Architectural patterns & principles
• Single-responsibility microservice
• Clear separation of concerns: HTTP server vs. business logic vs. external client vs. data models
• Twelve-factor app principles: config via env vars, containerized, stateless
• Kubernetes-native deployment: use Deployment + Service for high-availability
d. Key technologies & libraries
• Go modules (go.mod/go.sum)
• net/http for server & clients
• Docker for containerization
• Kubernetes for orchestration
• GitHub Actions for CI
Diagramming recommendations
• Orange for infrastructure (Docker Registry, Kubernetes)
• Purple for CI pipeline
Final checklist
• Components: Vmalert, Webhook Service (with submodules), VictoriaLogs, Slack, Docker Registry, Kubernetes, CI
• Flows: Alert inbound, log query, alert outbound, container build & deploy, CI trigger
• Infrastructure boundaries (external vs. cluster vs. code modules)
• Call out any important configuration (env vars, ports, paths)