Webhook Engine — Event-Triggered Automation

Überblick

Event-getriggerter Automatisierungsserver auf Port 8900. Empfängt Webhooks, wertet Regeln aus und führt Aktionen aus (Scripts ausführen, Alarme senden, Dienste neu starten, Loggen).

Standorte

Komponente	Pfad
Script	C:\Users\damir\scripts\webhook-engine.py
Regeln	C:\Users\damir\.webhook-engine\rules.json
Zustand	C:\Users\damir\.webhook-engine\state.json
Lock	C:\Users\damir\.webhook-engine\server.lock

Verwendung

# Server starten
python3 /c/Users/damir/scripts/webhook-engine.py --start

# Regel hinzufügen
python3 /c/Users/damir/scripts/webhook-engine.py --add-rule '{"event":"git-push","action":"send-alert"}'

# Regel mit Bedingung + Action-Dict
python3 /c/Users/damir/scripts/webhook-engine.py --add-rule '{"event":"cron-fail","condition":{"job_id":"backup"},"action":{"type":"run-script","path":"notify.py"}}'

# Regeln auflisten
python3 /c/Users/damir/scripts/webhook-engine.py --list-rules

# Log anzeigen (letzte 50 Events)
python3 /c/Users/damir/scripts/webhook-engine.py --log

# Regel entfernen
python3 /c/Users/damir/scripts/webhook-engine.py --remove-rule rule-1

# Log leeren
python3 /c/Users/damir/scripts/webhook-engine.py --clear-log

# Health-Check
python3 /c/Users/damir/scripts/webhook-engine.py --health

# Cron: Restart wenn down
python3 /c/Users/damir/scripts/webhook-engine.py --ensure-running

API Endpoints

Methode	Pfad	Beschreibung
POST	/webhook/<name>	Webhook empfangen (JSON-Body)
POST	/webhook	Generisches Event
GET	/health	Health-Check
GET	/rules	Regeln auflisten
GET	/state	Zustand anzeigen

Events

Standard-Event-Typen:

Event	Beschreibung	Typische Daten
git-push	Git Push	{"repo":"...","branch":"...","commits":[...]}
cron-fail	Cron-Job Fehler	{"job_id":"...","error":"..."}
threshold	Metrik-Schwellwert	{"metric":"...","value":42}

Der Event-Typ wird aus event oder event_type im JSON-Body gelesen; fällt der auf den Webhook-Namen zurück.

Actions

Action	Parameter	Beschreibung
run-script	path, args[]	Python-Script ausführen
send-alert	message	Alert ausgeben (stdout, für Monitoring)
restart-service	name	Service neustarten (taskkill/systemctl)
log-event	data	Daten loggen

Action als String (Kurzform)

{"event":"cron-fail","action":"send-alert"}

Action als Dict (mit Parametern)

{"event":"cron-fail","action":{"type":"run-script","path":"notify.py","args":["cron-fail"]}}

Bedingungen (Conditions)

Bedingungen verwenden Dot-Notation für den Zugriff auf Event-Daten:

{
  "event": "git-push",
  "condition": {"branch": "main"},
  "action": "send-alert"
}

{
  "event": "cron-fail",
  "condition": {"job_id": "backup"},
  "action": {"type": "run-script", "path": "alert_admin.py"}
}

Regelformat (rules.json)

[
  {
    "id": "rule-1",
    "event": "git-push",
    "condition": {"branch": "main", "repo": "openamer/openamer"},
    "action": {"type": "send-alert", "message": "Push on main: {branch}"}
  },
  {
    "id": "rule-2",
    "event": "cron-fail",
    "action": {"type": "run-script", "path": "notify.py"}
  }
]

Cron-Job (alle 5 Minuten)

Der Cron-Job webhook-engine-health prüft alle 5 Minuten, ob der Server läuft, und startet ihn bei Bedarf neu. Definiert in der OpenAmer jobs.json.

Manuelle Events senden (Test)

# git-push Event
curl -X POST http://localhost:8900/webhook/git \
  -H "Content-Type: application/json" \
  -d '{"event":"git-push","repo":"openamer/openamer","branch":"main","commits":["abc123"]}'

# cron-fail Event
curl -X POST http://localhost:8900/webhook/monitoring \
  -H "Content-Type: application/json" \
  -d '{"event":"cron-fail","job_id":"backup","error":"Timeout"}'

# threshold Event
curl -X POST http://localhost:8900/webhook/metrics \
  -H "Content-Type: application/json" \
  -d '{"event":"threshold","metric":"cpu","value":95}'

# Health-Check
curl http://localhost:8900/health

Troubleshooting

• Port 8900 already in use: netstat -ano | findstr :8900 → taskkill /PID <id> /F
• Rules not matching: Prüfe den Event-Namen im JSON-Body (event oder event_type Feld)
• Script not found: Pfad in rule["action"]["path"] muss relativ zu ~/scripts/ oder absolut sein
• Server hängt: taskkill /F /IM python.exe und Neustart
• Lock stale: Lösche C:\Users\damir\.webhook-engine\server.lock