Chat-Webhooks einrichten und testen

Zweck und Einsatzbereich

Unter Einstellungen → Slack / Teams hinterlegen Sie eine Incoming-Webhook-Adresse für einen Slack- oder Microsoft-Teams-Channel. Die Oberfläche kann die Verbindung mit einer festen NeuraPort-Testnachricht prüfen und zeigt je gespeichertem Ziel den Aktivstatus sowie die Zahl aufeinanderfolgender Versandfehler.

Wichtige Funktionsgrenze: Im geprüften Produktstand ist kein betrieblicher Ereignisweg mit dieser Chat-Webhook-Verteilung verbunden. Ein gespeichertes Ziel erhält daher derzeit nur ausdrücklich ausgelöste Testnachrichten. Die Beschreibung „um Ereignisse in einen Channel zu posten“ ist technisch vorbereitet, aber für reale Akten-, Rechnungs- oder Statusereignisse nicht produktiv verdrahtet.

Chat-Webhooks sind nicht mit den öffentlichen API-Webhooks für Systemintegrationen gleichzusetzen. Sie verwenden ein vom Chat-Anbieter ausgestelltes URL-Geheimnis und versenden menschenlesbare Nachrichten, keine signierten Geschäftsevent-Payloads.

Voraussetzungen und Berechtigungen

• Sie sind im richtigen Kundenmandanten angemeldet. Chat-Webhooks gelten organisationsweit und besitzen keinen eigenen Organisationseinheiten-Filter.
• Der Server erlaubt ADMIN und MANAGER das Auflisten, Anlegen, Ändern, Löschen und Testen. Plattformkonten sind ausdrücklich ausgeschlossen.
• Die aktuelle Einstellungsnavigation zeigt Slack / Teams nur einem ADMIN. Ein MANAGER besitzt trotz Serverberechtigung keinen regulären sichtbaren Bedienweg; verwenden Sie bis zur Korrektur ein vorgesehenes ADMIN-Konto.
• Für Chat-Webhooks ist keine separate Produktlizenz oder Modulfreischaltung belegt. OE-Zuweisung und aktive OE werden nicht als eigener fachlicher Scope ausgewertet.
• Sie besitzen eine neu erzeugte Incoming-Webhook-Adresse des vorgesehenen Slack- oder Teams-Channels und dürfen dort Testnachrichten veröffentlichen.
• Der Ziel-Channel enthält keine externen oder unberechtigten Mitglieder. Behandeln Sie die vollständige Webhook-Adresse wie ein Kennwort.

Die technische URL-Prüfung verlangt HTTPS, einen auflösbaren öffentlichen Host und blockiert bekannte lokale, private und Link-Local-Ziele. Sie bestätigt jedoch weder die Eigentümerschaft des Channels noch, dass eine als Slack beziehungsweise Teams bezeichnete URL wirklich zu diesem Anbieter gehört.

Schritt-für-Schritt-Anleitung

Ziel beim Chat-Anbieter vorbereiten

1. Legen Sie im vorgesehenen Slack-Workspace oder Microsoft-Teams-Bereich einen getrennten Incoming Webhook für NeuraPort an.
2. Wählen Sie einen Channel mit dem kleinsten erforderlichen Empfängerkreis. Verwenden Sie für Test und Produktion getrennte Ziele.
3. Dokumentieren Sie intern Zweck, Verantwortlichen, Empfänger, erlaubte Datenarten, Rotationsdatum und Abschaltverfahren.
4. Kopieren Sie die Webhook-Adresse nur unmittelbar für die Einrichtung. Speichern oder versenden Sie sie nicht in Tickets, Screenshots, E-Mails oder Chatnachrichten.

Die Anbieteroberfläche und ihre konkreten Menüs können sich ändern und sind nicht Teil von NeuraPort. Prüfen Sie die jeweils aktuelle Anbieterdokumentation und Organisationsrichtlinie.

Chat-Webhook anlegen

1. Öffnen Sie als ADMIN Einstellungen → Slack / Teams.
2. Wählen Sie Slack oder Teams passend zum Ziel.
3. Tragen Sie unter Name eine neutrale Zweckbezeichnung ein, beispielsweise Operations Test. Verwenden Sie keine Kundennamen oder Zugangsinformationen.
4. Fügen Sie die vollständige HTTPS-Adresse in das URL-Feld ein. Die Oberfläche verdeckt den Wert nicht; achten Sie auf Bildschirmfreigaben und Mitschnitte.
5. Wählen Sie Anlegen und warten Sie auf Webhook angelegt.
6. Prüfen Sie, ob der Eintrag mit richtiger Plattform und Status aktiv erscheint. Ein erfolgreicher Eintrag beweist noch nicht, dass die Zieladresse Nachrichten annimmt.

Die sichtbare Maske legt die Ereignisliste immer leer an. Technisch bedeutet dies „alle Ereignisse“. Da derzeit jedoch kein produktiver Ereignisaufruf angeschlossen ist, entstehen daraus noch keine automatischen Chatnachrichten. Eine Ereignisauswahl, Bearbeitung, Deaktivierung oder URL-Rotation ist in der Oberfläche nicht vorhanden.

Externe Testnachricht kontrolliert senden

1. Informieren Sie die Mitglieder des Test-Channels und stellen Sie sicher, dass der gespeicherte Webhook wirklich auf dieses Ziel zeigt.
2. Wählen Sie beim richtigen Eintrag Test. Der Klick führt sofort eine externe Schreibaktion aus: NeuraPort sendet die feste Nachricht NeuraPort Testnachricht mit dem Text Dies ist eine Testbenachrichtigung aus NeuraPort. an die gespeicherte Adresse. Es gibt keinen zusätzlichen Bestätigungsdialog.
3. Warten Sie auf Testnachricht gesendet oder Versand fehlgeschlagen. Klicken Sie nicht mehrfach, solange das Ergebnis unklar ist.
4. Prüfen Sie im Ziel-Channel Absender, Inhalt, Zeitpunkt und Empfängerkreis. Der Erfolg in NeuraPort bestätigt nur eine technisch akzeptierte Antwort, nicht die dauerhafte Zustellung oder Sichtbarkeit für die richtigen Personen.
5. Entfernen Sie einen nur für den Test verwendeten Webhook anschließend sowohl in NeuraPort als auch beim Chat-Anbieter.

Auch ein als inaktiv gespeicherter Webhook kann über die Testaktion direkt angesprochen werden. Der Aktivstatus wird beim Test nicht geprüft; behandeln Sie Test daher stets als tatsächlichen externen Versand.

Fehler beheben, rotieren oder entfernen

1. Prüfen Sie bei Versand fehlgeschlagen zuerst, ob die Adresse beim Anbieter noch aktiv ist und zum vorgesehenen Channel gehört. Geben Sie die URL nicht in Diagnoseprotokolle oder Supporttexte ein.
2. Die sichtbare Fehlerzahl steigt bei einer abgelehnten Antwort oder einem Netzwerkfehler und wird nach erfolgreichem Versand wieder auf null gesetzt. Sie enthält keine Fehlerursache und keine Versandhistorie.
3. Da Bearbeiten und Deaktivieren in der Oberfläche fehlen, legen Sie bei einer URL-Rotation einen neuen Webhook an, testen ihn kontrolliert und wählen anschließend beim alten Eintrag Entfernen.
4. Bestätigen Sie Webhook entfernen?. Der Eintrag wird endgültig gelöscht; eine Archiv- oder Wiederherstellungsfunktion ist nicht vorhanden.
5. Widerrufen Sie die alte Adresse zusätzlich beim Chat-Anbieter. Das Entfernen in NeuraPort macht ein beim Anbieter weiterhin aktives URL-Geheimnis nicht automatisch ungültig.

Feldreferenz

Feld	Pflicht	Bedeutung	Validierung
Plattform	Ja	Nachrichtenformat für Slack oder Teams	Nur SLACK und TEAMS werden akzeptiert; Anbieter und URL-Domain werden nicht miteinander abgeglichen. Nach Anlage nicht sichtbar änderbar.
Name	Ja	Interne Zweckbezeichnung des Ziels	Bei Anlage 1 bis 120 Zeichen; Oberfläche verhindert nur einen leeren Wert. Keine Eindeutigkeitsprüfung.
Webhook-URL	Ja	Geheime externe Incoming-Webhook-Adresse	Bei Anlage 8 bis 1000 Zeichen, muss mit https:// beginnen, öffentlich auflösbar sein und darf nicht auf blockierte interne Netze zeigen. Keine Anbieter- oder Eigentumsprüfung.
Ereignisse	Technisch	Liste abonnierter Ereignisnamen	Sichtbare Anlage sendet eine leere Liste; technisch bedeutet leer „alle“. Keine sichtbare Auswahl oder serverseitige Werteliste.
Status	Systemseitig / technisch änderbar	aktiv oder inaktiv	Sichtbare Oberfläche bietet keinen Schalter. Reguläre Verteilung berücksichtigt nur aktive Ziele; Test ignoriert den Status.
Fehler	Systemseitig	Zahl aufeinanderfolgender fehlgeschlagener Versandversuche	Erfolg setzt auf 0 zurück. Unsichere Zieladresse deaktiviert das Ziel, ohne die Fehlerzahl zu erhöhen. Keine Fehlerdetails in der UI.
Letzter Versand	Systemseitig	Zeitpunkt des letzten technisch erfolgreichen Versands	Wird gespeichert, aber in der aktuellen Oberfläche nicht angezeigt. Kein Zustell- oder Lesebeleg.
Test	Aktion	Sendet sofort eine feste externe Testnachricht	Kein Bestätigungsdialog, kein Schutz gegen wiederholtes Klicken und keine Prüfung des Aktivstatus.
Entfernen	Aktion	Löscht die Konfiguration nach Rückfrage	Endgültige Löschung in NeuraPort; widerruft das URL-Geheimnis beim Anbieter nicht.

Status und mögliche Übergänge

Ausgang	Aktion	Ergebnis
Kein Chat-Webhook	Anlegen	Organisationsweiter Eintrag wird standardmäßig aktiv mit leerer Ereignisliste gespeichert.
Webhook aktiv	Test	Externe Testnachricht wird sofort versucht; Erfolg aktualisiert letzten Versand und setzt Fehler auf 0.
Webhook inaktiv	Test	Externe Testnachricht wird trotzdem sofort versucht.
Versand abgelehnt oder Netzwerkfehler	Test oder vorbereitete Verteilung	Ergebnis sent=false, Fehlerzahl steigt um 1; auslösender Fachvorgang würde durch den Best-Effort-Versand nicht abgebrochen.
Versand erfolgreich	Test oder vorbereitete Verteilung	Ergebnis sent=true, letzter Versand wird gesetzt und Fehlerzahl auf 0 zurückgesetzt.
Zieladresse wird bei Versand als unsicher erkannt	Test oder vorbereitete Verteilung	Webhook wird inaktiv, Versand unterbleibt; Fehlerzahl bleibt unverändert.
Gespeicherter Webhook	Entfernen bestätigen	Eintrag wird endgültig gelöscht; Anbieteradresse bleibt außerhalb NeuraPorts bestehen.

Eine automatische Deaktivierung nach einer bestimmten Zahl normaler Provider- oder Netzwerkfehler ist nicht implementiert. Die Fehlerzahl ist daher ein Hinweis, kein Circuit Breaker und kein Alarm.

Was im Hintergrund passiert

Der Webhook wird mit Organisation, Plattform, Name, vollständiger URL, Ereignisliste, Aktivstatus, Ersteller, Erstellzeitpunkt, letztem erfolgreichen Versand und Fehlerzahl gespeichert. Die Datensätze werden mandantenbezogen gefiltert und zusätzlich durch Datenbankrichtlinien getrennt. Organisationseinheiten werden nicht gespeichert oder ausgewertet.

Die vollständige Webhook-Adresse wird im aktuellen Stand im Klartext gespeichert und über die Verwaltungsantwort zurückgegeben. Sie ist ein Secret, aber weder verschlüsselt noch in der technischen Antwort maskiert. Begrenzen Sie deshalb Administratorzugriff, Bildschirmaufnahmen und Diagnoseausgaben und rotieren Sie eine möglicherweise offengelegte Adresse sofort beim Anbieter.

Vor Anlage, Änderung und Versand wird die Zieladresse auf Schema, Hostauflösung und private beziehungsweise lokale Zielnetze geprüft. Dies reduziert Server-Side-Request-Forgery-Risiken, bindet die Adresse jedoch nicht an Slack oder Teams. Zwischen Prüfung und tatsächlicher Verbindung findet eine neue Namensauflösung statt; die Prüfung ist deshalb kein vollständiger Schutz gegen manipulierte DNS-Ziele.

Slack erhält einen einfachen Textblock. Teams erhält eine MessageCard im älteren Connectorformat. Eine optionale Aktenverknüpfung ist technisch vorbereitet, wird von der festen Testnachricht aber nicht verwendet. Andere Chatplattformen sind nicht unterstützt.

Der Versand wartet höchstens ungefähr fünf Sekunden und gilt bei jeder Antwort im Bereich 200 bis 299 als erfolgreich. Andere Antworten oder Verbindungsfehler erhöhen die Fehlerzahl. Die sichtbare Oberfläche zeigt weder Antwortcode noch Fehlertext, letzten Versand, Ereignisliste oder URL.

Die Verteilfunktion könnte aktive Ziele nach Ereignis filtern; eine leere Ereignisliste bedeutet alle Ereignisse. Im geprüften Produktcode ruft jedoch kein betrieblicher Prozess diese Chat-Verteilung auf. Automatische Ereignisnachrichten sind deshalb nicht belegt. Die ähnlich benannten öffentlichen API-Webhooks verwenden einen anderen Integrationsweg.

Automatisierte Tests decken Slack- und Teams-Formatierung, Anlage, Auflistung, technische Änderung, Löschung, gemockten Testversand, Ereignisfilterung und mehrere interne beziehungsweise lokale SSRF-Ziele ab. Nicht ausreichend geprüft sind Manager-UI, Mandanten- und Datenbanktrennung dieses Moduls, Secret-Verschlüsselung und Maskierung, Anbieter-Domainbindung, DNS-Rebinding, inaktiver Testversand, Fehler- und Wiederholungsverhalten, parallele Tests sowie ein echter betrieblicher Ereignisaufruf.

Typische Fehler und Lösungen

Meldung oder Beobachtung	Ursache	Lösung
Slack / Teams fehlt bei MANAGER	Serverberechtigung und aktuelle Navigation stimmen nicht überein	Vorgesehenes ADMIN-Konto verwenden und fehlenden Manager-Bedienweg als Produktabweichung behandeln.
Noch keine Webhooks. trotz erwartetem Eintrag	Bestand ist leer oder Laden ist fehlgeschlagen; die Oberfläche trennt beides nicht klar	Sitzung, Mandant und Verbindung prüfen. Nicht sofort eine doppelte Konfiguration anlegen.
Ungueltige Plattform	Wert ist weder Slack noch Teams	Eine der beiden sichtbaren Plattformen wählen; andere Chatdienste sind nicht belegt.
Webhook-URL muss mit https:// beginnen	Adresse nutzt HTTP oder enthält keinen vollständigen HTTPS-Anfang	Neue Incoming-Webhook-Adresse direkt beim vorgesehenen Anbieter erzeugen. Keine URL manuell „reparieren“.
Webhook-URL nicht erlaubt: …	Host fehlt, ist nicht auflösbar oder zeigt auf ein blockiertes internes Ziel	Ziel und DNS durch einen Administrator prüfen. Schutz nicht umgehen und keine interne Adresse verwenden.
Aktion fehlgeschlagen	Speicherung, Sitzung oder Berechtigung wurde abgelehnt	Mandant, Rolle, Eingaben und Verbindung prüfen; geheime URL nicht in Supporttext kopieren.
Testnachricht gesendet, aber Nachricht fehlt	Anbieter hat technisch akzeptiert, Ziel-Channel, App oder Berechtigung passt jedoch nicht	Channel beim Anbieter prüfen und bei Unsicherheit eine neue Adresse erzeugen. Erfolg ist kein Lesebeleg.
Versand fehlgeschlagen	Provider antwortet nicht erfolgreich, Netzwerkfehler oder unsichere Zielauflösung	Nicht mehrfach klicken; Anbieterstatus, Adresse und Fehlerzahl prüfen und bei Bedarf kontrolliert rotieren.
Fehlerzahl steigt weiter	Jeder weitere fehlgeschlagene Versuch erhöht den Zähler; keine automatische Sperre	Test stoppen, Ursache klären und Ziel entfernen oder beim Anbieter widerrufen.
Inaktiver Webhook sendet Test	Testpfad prüft den Aktivstatus nicht	Test nicht als harmlose lokale Prüfung behandeln; altes Ziel entfernen und beim Anbieter widerrufen.
Nach Entfernen funktioniert die alte Adresse weiter	NeuraPort löscht nur seine Konfiguration	Webhook zusätzlich im Slack- oder Teams-Administrationsbereich widerrufen.
Keine automatischen Akten- oder Statusnachrichten	Betriebliche Ereignisquellen rufen die vorbereitete Chat-Verteilung derzeit nicht auf	Funktion nur als Testkonfiguration einordnen und produktive Verdrahtung samt Ereigniskatalog erst implementieren und abnehmen lassen.
Webhook-Adresse war in Antwort, Screenshot oder Protokoll sichtbar	Adresse wird nicht verschlüsselt beziehungsweise maskiert behandelt	Adresse beim Anbieter sofort widerrufen, neu erzeugen und alle Kopien aus kontrollierbaren Ablagen entfernen.

Verwandte Themen

• Öffentliche API und Webhooks einrichten
• Systemzugriff für Integrationen verwalten
• Organisationsrollen und Zugriffsreviews verwalten
• Zugriffsbereich und Datensicht verstehen
• Lizenzstatus und Zugriffsprobleme einordnen
• Organisation, Berichte und Audit verwenden