Einheit 1 — Wie ein Messenger-Bot funktioniert

Was du nach dieser Einheit weißt: Du verstehst den Weg einer Nachricht vom Messenger in deinen Workflow und zurück, kennst die Schutzmaßnahmen für den Eingang und weißt, welche Netzwerkverbindungen dafür nötig sind.

Zwei Richtungen, zwei Techniken

Ein Bot ist für den Messenger ein Teilnehmer wie jeder andere. Technisch besteht er aus zwei getrennten Wegen:

                       ①  Webhook (HTTP POST)
  ┌─────────────┐  ─────────────────────────────→  ┌──────────────────┐
  │  Messenger   │                                   │  42°OS-Workflow  │
  │ (Talk, Chat, │  ←─────────────────────────────  │                  │
  │   Teams)     │       ②  API-Aufruf (HTTP POST)  └──────────────────┘
  └─────────────┘

① Eingang: Schreibt jemand dem Bot, ruft der Messenger eine URL auf — die URL eines Webhook Agents in 42°OS. Im Request-Body steht die Nachricht.

② Antwort: Der Workflow schickt seine Antwort mit einem Post Agent an die Schnittstelle des Messengers. Dafür braucht er einen Zugang (Token, Secret oder Client-Zugangsdaten).

Warum die Antwort nicht im Eingang zurückgeht

Technisch könnte der Webhook Agent die Antwort direkt in seiner HTTP-Antwort mitschicken. Das funktioniert aber nicht für Workflows, die arbeiten müssen:

• Messenger warten nur wenige Sekunden auf die HTTP-Antwort (Teams: 5 bis 15 Sekunden). Eine KI-Erkennung, eine Datenbankabfrage und eine Antwortformulierung dauern oft länger.
• Wartet der Messenger vergeblich, wiederholt er die Zustellung — und der Workflow bekommt dieselbe Nachricht zweimal.
• Die HTTP-Antwort des Webhook Agents ist ein fester Text, keine dynamische Antwort.

Deshalb gilt für alle Messenger in diesem Kurs dasselbe Muster:

1. Der Webhook Agent antwortet sofort mit 200 OK und einem festen Text.
2. Der Workflow arbeitet in Ruhe.
3. Die eigentliche Antwort geht später per Post Agent an den Messenger.

Der Webhook Agent

Die Adresse eines Webhook Agents hat diese Form:

https://<deine-42os-instanz>/users/<USER-ID>/web_requests/<AGENT-ID>/<SECRET>

Du findest sie in der Konfiguration des Agents, sobald er gespeichert ist. Für Messenger-Bots bewährt sich diese Einstellung:

Option	Wert	Warum
secret	lange Zufallszeichenkette	Teil der URL; ohne das richtige Secret antwortet der Agent mit 404
verbs	post	Messenger senden nur POST
payload_path	.	den ganzen Body übernehmen
response	OK	fester Text, wird vom Messenger ignoriert
code	200	manche Messenger werten 201 als Fehler
ip_allowlist	IP-Adresse(n) des Messenger-Servers	siehe unten

Den Eingang schützen

Eine Webhook-URL ist im Internet erreichbar. Wer sie kennt, könnte deinem Workflow Nachrichten unterschieben — im Namen einer beliebigen Person. Schütze den Eingang deshalb mehrfach:

1. Geheime URL. Das secret ist Teil der URL. Behandle die ganze URL wie ein Passwort: nicht in Tickets, Chats oder Screenshots.

2. IP-Freigabe. Wenn dein Messenger im eigenen Haus läuft (Nextcloud, Synology), kennst du seine öffentliche IP-Adresse. Trage sie in ip_allowlist ein — dann nimmt der Agent nur Anfragen von dort an.

3. Echtheitsprüfung des Messengers. Jeder Messenger bietet einen eigenen Nachweis, dass die Nachricht wirklich von ihm kommt:

Messenger	Nachweis
Nextcloud Talk	HMAC-Signatur im Header X-Nextcloud-Talk-Signature
Synology Chat	Bot-Token im Feld token des Bodys
Microsoft Teams (Bot)	signiertes JWT im Header Authorization

Die Option hmac_secret des Webhook Agents erwartet das Format X-Hub-Signature-256 (GitHub-Stil) — keiner der drei Messenger nutzt dieses Format. Die Prüfung erfolgt deshalb im JavaScript Agent direkt nach dem Eingang, wo das möglich ist. Wo der Workflow die nötigen Header nicht sieht oder die Prüfung zu aufwendig ist, sind geheime URL und IP-Freigabe zusammen ein solider Schutz.

4. Absenderprüfung. Unabhängig davon prüft dein Workflow die technische ID der Person gegen eine Liste berechtigter Nutzer (Kurs 7, Einheit 2). Selbst eine echte Nachricht von einer unbekannten Person führt dann zu nichts.

Netzwerk: Wer muss wen erreichen?

Beide Richtungen brauchen eine funktionierende Verbindung:

Richtung	Voraussetzung
Messenger → 42°OS	Der Messenger-Server darf ausgehende HTTPS-Verbindungen zu deiner 42°OS-Instanz aufbauen
42°OS → Messenger	Deine 42°OS-Instanz erreicht die API des Messengers

Bei Microsoft Teams ist beides unproblematisch: Teams ist ein Cloud-Dienst. Bei Nextcloud und Synology hängt es davon ab, wo die Systeme stehen:

• Messenger öffentlich erreichbar (die übliche Einrichtung, damit Mitarbeitende auch unterwegs chatten können): beide Richtungen funktionieren ohne weitere Maßnahmen.
• Messenger nur im internen Netz: 42°OS in der Cloud kann ihn nicht erreichen. Dann brauchst du eine VPN-Verbindung (Kurs 3, Einheit VPN) oder eine 42°OS-Instanz im selben Netz (Modul 7 — Deployment-Modelle).

Selbst signierte Zertifikate

Viele NAS-Systeme und interne Server nutzen selbst signierte Zertifikate. Der Post Agent lehnt sie ab. Die Option disable_ssl_verification hilft zwar, schaltet aber eine wichtige Prüfung ab. Besser ist ein gültiges Zertifikat, zum Beispiel über Let's Encrypt — Synology DSM und Nextcloud bieten das direkt an.

Kurzer Selbst-Check

Warum antwortet der Webhook Agent immer nur mit einem festen „OK“?

Weil die eigentliche Antwort Zeit braucht. Der Messenger soll sofort wissen, dass die Nachricht angekommen ist — sonst stellt er sie erneut zu. Die inhaltliche Antwort geht danach über die API des Messengers.

Dein Nextcloud-Server steht im Firmennetz, 42°OS läuft in der Cloud. Welche Richtung funktioniert ohne weitere Maßnahmen?

Nur der Eingang — sofern der Nextcloud-Server ins Internet darf. Für die Antwort muss 42°OS den Nextcloud-Server erreichen. Ist er nur intern erreichbar, braucht es eine VPN-Verbindung oder eine 42°OS-Instanz im Firmennetz.