ALAMOS-Einsatzalarm → Zammad-Ticket (n8n)
Quelle: pkr-lab/pkr-lab-docs/capulus/capulus-core/3-apps-workloads/300h0-alamos-einsatz-zammad.md
ALAMOS-Einsatzalarm → Zammad-Ticket (n8n)
Cluster: TECH · Ordner
argocd/apps/tech/n8n/workflows/· Zugang: n8n-Workflow, Webhook über alamos-relay.kubectl-Befehle in diesem Doc gelten für den TECH-Cluster (Zugriff je Cluster).
Erweitert die reine Kiosk-Anzeige aus
30010-alamos-apager.md um eine
Push-Benachrichtigung: Kommt in ALAMOS AMweb ein echter Einsatz rein, legt
ein n8n-Workflow automatisch ein Zammad-Ticket mit den mitgelieferten
Einsatzdaten an — die Mail-Benachrichtigung übernimmt danach Zammads
eigene Agenten-Benachrichtigung, wie bei den anderen n8n→Zammad-Workflows
in diesem Repo (siehe 30070-n8n.md).
Wichtige Einschränkung, bevor ihr das aufsetzt: Welche Felder ALAMOS
AMweb im Webhook tatsächlich mitliefert (Adresse, Fahrzeuge, Meldebild,
...), war ohne einen eingeloggten Alamos-Account nicht zu ermitteln — nur
keyword (Einsatzstichwort) und unit (Einheit) sind laut öffentlichem
Handbuch als Standard-Platzhalter dokumentiert. Der Workflow ist deshalb
bewusst datenoffen gebaut: er gibt alle Felder aus, die der Webhook
mitliefert, unabhängig davon, wie sie heißen. Die vollständige Recherche
inkl. offener Fragen steht in
capulus-core/4-planung/40060-alamos-einsatz-email-benachrichtigung.md.
Architektur
Der einzige Auslöser dieses Workflows ist der ALAMOS-Webhook selbst —
kein Polling. Ohne die Ziel-URL im Alamos-Account einzutragen (siehe
Einrichtung, Schritt 5) läuft der Workflow nie an und es
entsteht nie ein Ticket, egal wie viele echte Einsätze reinkommen.
Update — direkter Aufruf hat sich als nicht zuverlässig erwiesen, Fix:
alamos-relay. Der ursprünglich hier
empfohlene direkte Aufruf von n8n.prod.homeserver aus AMweb heraus hat in
der Praxis nicht funktioniert (vermutlich genau das unten beschriebene
Private-Network-Access-Problem, ggf. auch weil "Allgemeine Webhooks"
serverseitig von Alamos' Cloud statt aus dem Browser-Tab feuert). Statt n8n
selbst öffentlich zu machen — was die bewusste Entscheidung „n8n nicht aus dem Internet erreichbar“ aufheben würde
(c0030: aus dem Cloudflare-Tunnel entfernt, Security) — steht jetzt ein eigener, minimaler Proxy dazwischen:
alamos-relay. Die Ziel-URL in der
Alamos-Webhook-Konfiguration zeigt seitdem auf das Relay, nicht mehr auf
n8n.prod.homeserver direkt (siehe Einrichtung unten,
Schritt 4). Der Rest dieses Abschnitts (welche Webhook-Variante, warum,
das PNA-Risiko) bleibt als Hintergrund stehen — er erklärt, warum das
Relay überhaupt nötig wurde.
Empfehlung: AMweb-Seiteneinstellung-Webhook nutzen, nicht "Allgemeine
Webhooks" — nur für Ersteren ist öffentlich dokumentiert, dass der Aufruf
aus dem Browser-Tab heraus feuert, also von der Kiosk-Chromium-Session
selbst, die ohnehin schon im LAN/Tailscale hängt und *.homeserver
auflöst (identisch dazu, wie der Kiosk die echte AMweb-Seite lädt). Bei
"Allgemeine Webhooks" (Account-Ebene) war öffentlich nicht zu klären, ob
der Call stattdessen von Alamos' Cloud-Servern selbst kommt (also wirklich
aus dem öffentlichen Internet) — seit dem Umweg über
alamos-relay ist das allerdings für beide
Varianten egal: die Ziel-URL ist so oder so öffentlich erreichbar, ohne
dass n8n selbst öffentlich wird.
Zusätzliches Risiko, unabhängig von der Webhook-Variante — Private
Network Access: Die AMweb-Seite selbst wird von einer öffentlichen
Origin (amweb.alamos.cloud o. ä.) geladen. Moderne Chromium-Versionen
blockieren per Private Network Access standardmäßig JS-Requests
(fetch/XHR) von einer öffentlichen Seite zu einer privaten
Netzwerk-Adresse — und n8n.prod.homeserver löst intern auf eine private
IP auf. Das deckt sich vermutlich mit der Handbuch-Warnung "Aufruf lokaler
URLs... wird i. d. R. vom Browser aus Sicherheitsgründen blockiert" (die
könnte mehr meinen als nur localhost). Genau dieses Problem löst
alamos-relay: dessen öffentlicher Hostname
löst auf eine Cloudflare-IP auf, PNA greift also nicht mehr, unabhängig
davon, ob der Call aus dem Kiosk-Browser-Tab oder direkt von Alamos'
Cloud-Servern kommt.
ALAMOS AMweb (Cloud-Dienst)
│ Webhook, GET oder POST, nur bei echten Alarmen
│ (AMweb-Seiteneinstellung ODER "Allgemeine Webhooks" im Alamos-Admin)
│ Ziel-URL MUSS dort eingetragen sein, siehe Einrichtung Schritt 4-5
▼
https://alamos-relay-prod.pke-lab.de/relay/<TOKEN>
│ alamos-relay (öffentlich erreichbarer Proxy, siehe 300i0) —
│ Server-zu-Server-Forward, kein Browser/PNA mehr im Spiel
▼
http://n8n.prod.homeserver/webhook/alamos-einsatz
│
├─ Webhook (GET) ─┐
├─ Webhook (POST) ─┤ beide Trigger teilen sich denselben Pfad
│ ▼
│ Code-Node "Einsatzdaten aufbereiten"
│ - führt Query-Parameter (GET) und JSON-Body (POST) zusammen
│ - baut Ticket-Titel aus keyword/unit, falls vorhanden
│ - gibt ALLE empfangenen Felder unverändert im Ticket-Text aus
│ - filtert Mehrfach-Auslösungen desselben Alarms innerhalb von
│ 2 Minuten (Workflow-Static-Data, siehe unten)
▼
Zammad-Ticket erstellen (nativer n8n-nodes-base.zammad-Node, Ticket→Create,
Gruppe Support::Administration)
│
▼
Zammads Agenten-Benachrichtigung → Mail an [email protected]
Workflow-Datei:
argocd/apps/tech/n8n/workflows/alamos-einsatz-to-zammad.json.
Nutzt bewusst den nativen n8n-nodes-base.zammad-Node (wie
nightly-worker-update-to-zammad.json/yearly-secrets-rotation-reminder.json),
nicht den rohen HTTP-Request-Node wie im älteren
banana-pi-down-to-zammad.json — andere Credential (Typ „Zammad Token Auth
API“ statt Header-Auth), siehe Einrichtung.
Warum zwei Webhook-Trigger auf demselben Pfad
Ob eure Alamos-Konfiguration den Alarm per GET (Query-Parameter) oder POST
(JSON-Body) verschickt, hängt davon ab, welche der beiden
Webhook-Varianten ihr einrichtet (siehe Planungsdokument). Beide
Trigger-Nodes registrieren denselben Pfad alamos-einsatz, aber
unterschiedliche HTTP-Methoden — dadurch funktioniert der Workflow mit
beiden Varianten, ohne dass vorher geklärt sein muss, welche ihr nutzt.
Leere Test-Calls werden übersprungen, nicht geticketet
Fehlen sowohl keyword als auch unit im zusammengeführten Payload,
bricht der Code-Node ohne Ticket ab (return [], kein Fehler) — nur
eine console.log-Zeile mit den Rohdaten landet im Execution-Log. Das
deckt Verbindungstests ab, die keine echten Einsatzdaten mitschicken (z. B.
ein reiner curl gegen alamos-relay ohne
Query-Parameter, oder eine Alamos-"Webhook Test"-Funktion ohne konkrete
Alarmauswahl) — genau das ist beim ersten Verbindungstest des Relays
passiert (leerer GET-Call, alamos-relay antwortete 200, aber ohne
diesen Guard hätte der Code-Node trotzdem ein Ticket mit leerem Titel
erzeugt). Bewusst kein Error/Exception: ein console.log statt eines
harten Fehlers, damit ein Test-Call nicht wie ein defekter Workflow
aussieht, aber trotzdem im Execution-Log nachvollziehbar bleibt — falls
ein echter Alarm aus unerwarteten Gründen (z. B. andere Feldnamen als
keyword/unit) denselben Weg nimmt, ist das damit nicht komplett
unsichtbar, sondern zumindest im Log sichtbar, nur eben nicht per Ticket.
Duplikat-Schutz
Falls der Webhook pro geöffnetem Kiosk-Tab feuert (statt zentral einmal
pro Konto — auch das ist eine der offenen Fragen im Planungsdokument),
würden bei bis zu drei gleichzeitig laufenden Alarmmonitor-Standorten
(30010, 30020)
bis zu drei Tickets für denselben Einsatz entstehen. Der Code-Node merkt
sich deshalb Stichwort|Einheit (oder den kompletten Payload, falls
keyword/unit fehlen) für 2 Minuten in n8n-Workflow-Static-Data und
überspringt inhaltsgleiche Wiederholungen innerhalb dieses Fensters —
wichtig: Das ist reiner In-Memory-Zustand, ein n8n-Neustart löscht ihn
(unkritisch, da echte Mehrfach-Auslösungen desselben Alarms innerhalb von
Sekunden eintreffen, nicht nach einem Neustart).
Einrichtung
- Voraussetzung: Zammad-API-Token mit Berechtigung
ticket.agent
vorhanden. Achtung: Der native Zammad-Node braucht eine Credential
vom Typ „Zammad Token Auth API" (zammadTokenAuthApi) — das ist
ein anderer Credential-Typ als die Header-Auth-Credential "Zammad
API Token", diebanana-pi-down-to-zammad.jsonnutzt; die beiden lassen
sich nicht wiederverwenden, auch wenn derselbe Zammad-Token dahinter
stehen kann. Falls schon fürnightly-worker-update-to-zammad.jsonoder
yearly-secrets-rotation-reminder.jsoneine Credential dieses Typs
angelegt wurde (z. B. "Zammad Token Auth (Rotation-Reminder)"), kann die
wiederverwendet werden, sofern sie auf dieselbe Zammad-Instanz zeigt.
Sonst Token neu erzeugen wie in
f0040-github-release-watcher.md, Schritt 1
beschrieben, Credential in n8n neu anlegen: Typ "Zammad Token Auth API",
Base URLhttps://zammad.tech.homeserver(nichthttp://: der TECH-Traefik antwortet auf HTTP mit308, und der Zammad-Node folgt dem bei POST nicht), „Ignore SSL Issues“ aus. n8n vertraut der Homeserver-Root-CA überNODE_EXTRA_CA_CERTS, siehe 30070. Access Token aus Schritt 1. - n8n:
alamos-einsatz-to-zammad.jsonimportieren, im Node
"Zammad-Ticket erstellen" die Credential aus Schritt 1 zuweisen —
Credential-IDs werden beim Import nicht übernommen, normaler
Post-Import-Schritt.
In den beiden Webhook-Nodes („Webhook (GET)“, „Webhook (POST)“) das
CredentialWebhook alamos-einsatz(Header Auth) zuweisen. Es enthält
dasselbe Bearer-Token wie der Schlüsseln8nTokenim Secret von
alamos-relay, siehe
30070. Ohne gültigen Header
antwortet der Webhook mit403. - Workflow in n8n aktivieren (Import allein reicht nicht).
- alamos-relay ausrollen (eigener Chart, eigenes
Token) und die öffentliche Relay-URL zusammensetzen:
https://alamos-relay-prod.pke-lab.de/relay/<TOKEN>— nicht mehr
http://n8n.prod.homeserver/webhook/alamos-einsatzdirekt, siehe
Architektur oben. - Im Alamos-Account (mit eurem bestehenden Login) — dieser Schritt
ist zwingend, ohne ihn feuert der Workflow nie: Webhook-Konfiguration
der AMweb-Seiteneinstellung öffnen (nicht "Allgemeine Webhooks",
siehe Begründung oben unter Architektur), obige Relay-URL als Ziel
eintragen. Dabei gleich in der Vorschau/"Webhook Test" nachsehen, welche
Platzhalter tatsächlich angeboten werden — das beantwortet die im
Planungsdokument offene Frage nach den exakten Feldnamen. - Zammad: Sicherstellen, dass
[email protected](oder die
gewünschte Zieladresse) Agent in der GruppeSupport::Administration
ist und unter Profil → Benachrichtigungen die Mail-Benachrichtigung
für "Neues Ticket" aktiviert hat (Zammad-Standard: aktiviert). - Testauslösung: entweder auf einen echten Einsatz warten, oder — falls
Alamos eine "Webhook Test"-Funktion in der Konfiguration anbietet —
darüber einen Testaufruf schicken.
Anpassungen
- Andere Zammad-Gruppe/Empfänger:
ZAMMAD_GROUP/
ZAMMAD_REQUESTER_EMAILam Kopf des Code-Node "Einsatzdaten
aufbereiten" ändern.ZAMMAD_REQUESTER_EMAILmuss ein bereits
existierender Zammad-User sein (siehe
f0040, Schritt 3
für die Details zu dieser Einschränkung). - Dedup-Fenster ändern:
DEDUP_WINDOW_MSim selben Code-Node. - Rückmeldungen ("wer kommt") ergänzen: Noch nicht umgesetzt — hängt an
zwei ungeklärten Voraussetzungen (passendealarmIdaus dem
Webhook-Payload, "Online-Service"-Accountstatus), siehe Abschnitt
"Rückmeldungen alarmierter Personen" im Planungsdokument.
Fehlerbehebung
| Symptom | Check |
|---|---|
| Kein Zammad-Ticket bei echtem Einsatz | Workflow in n8n aktiv? kubectl -n n8n logs deploy/n8n (bzw. n8n-UI → Executions) — kommt der Webhook überhaupt an? Execution-Log der "Einsatzdaten aufbereiten"-Node ansehen: falls dort Kein keyword/unit im Payload geloggt wird, obwohl es ein echter Alarm war, liefert eure Alamos-Instanz die Daten unter anderen Feldnamen als keyword/unit — Rohdaten aus dem Log in Anpassungen berücksichtigen |
Test-Call (z. B. curl gegen alamos-relay ohne Query-Parameter) erzeugt kein Ticket |
Erwartetes Verhalten, siehe Leere Test-Calls werden übersprungen — kein Fehler, nur ein Log-Eintrag |
| Ticket wird unterdrückt, obwohl es ein neuer Einsatz war | DEDUP_WINDOW_MS zu großzügig, oder keyword/unit fehlen und der Fallback-Payload-Vergleich trifft zufällig — Rohdaten in der n8n-Execution ansehen |
| Ticket erstellt, aber keine Mail | Zammad-Agenten-Mitgliedschaft/Benachrichtigung prüfen (siehe oben), ausgehender E-Mail-Kanal in Zammad konfiguriert? |
| n8n-Workflow schlägt am Zammad-Node fehl | Credential vom Typ "Zammad Token Auth API" zugewiesen (nicht die Header-Auth-Credential aus banana-pi-down-to-zammad.json)? Base URL korrekt (https://zammad.tech.homeserver; mit http:// kommt 308 Permanent Redirect)? Token gültig/ticket.agent-Berechtigung? |
| Webhook kommt gar nicht in n8n an | Erst alamos-relay prüfen (kubectl -n alamos-relay logs deploy/alamos-relay, korrektes Token in der Alamos-Konfiguration?) — kommt der Call dort schon nicht an, liegt es an Alamos/DNS, nicht an n8n. Kommt er beim Relay an, aber nicht bei n8n: NetworkPolicy-Rollout aus 300i0, Rollout vollständig durchgelaufen? |
Relevante Links
- capulus-core/3-apps-workloads/300i0-alamos-relay.md — öffentlicher Proxy vor n8n, Fix für den direkten Aufruf
- capulus-core/4-planung/40060-alamos-einsatz-email-benachrichtigung.md — Recherche zu ALAMOS-Schnittstellen, offene Fragen
- capulus-core/3-apps-workloads/30010-alamos-apager.md — Basis-Architektur (Kiosk-Anzeige)
- capulus-ansible/3-apps-workloads/30020-vereinsheim-alarmmonitor.md, Zammad-Ticket via n8n — analoges Vorbild-Muster (Ausfall statt Einsatz)
- capulus-core/3-apps-workloads/30070-n8n.md — n8n-Setup
- capulus-core/f-cicd-automatisierung/f0040-github-release-watcher.md — Zammad-API-Token/Gruppe/Requester-Regeln