Benachrichtigungskanal aktualisieren

PATCH /api/notification-channels/:id

Die Config wird mit den bestehenden Geheimnissen zusammengeführt (merged), wobei verschlüsselte Felder, die nicht übergeben werden, erhalten bleiben, solange der Kanal seinen type behält.

Ein Wechsel des type verhält sich anders: Die gespeicherte Config gehört zum alten Kanaltyp, sie wird komplett verworfen und die Config wird aus der config dieser Anfrage neu aufgebaut. Ein Typwechsel braucht deshalb zwingend config (sonst 400), und Geheimnisse des alten Typs werden nicht übernommen.

Anfrage (Request Body) (alle optional)Ankerlink kopieren

delaySeconds läuft für diesen Kanal auf einer eigenen Uhr, beginnend in dem Moment, in dem dieser Kanal benachrichtigen würde, unabhängig von jedem anderen Kanal am selben Alarm. Beginnt in dieser Zeit ein Wartungsfenster oder ist die Störung bis dahin bereits behoben, wird auf diesem Kanal nichts mehr zugestellt.

priority ist aus der Kanalkonfiguration entfernt. Eine Anfrage, die das Feld noch mitschickt, wird weiterhin angenommen, das Feld wird einfach ignoriert, sodass bestehende Integrationen unverändert weiterlaufen.

Beispiel (cURL)Ankerlink kopieren

curl -X PATCH "$BASE_URL/api/notification-channels/1" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Email Channel",
    "isActive": true
  }'

Häufige FehlerAnkerlink kopieren

• 400 Bad Request mit data.code invalidRequestBody, wenn ein email- oder sms-Kanal einen Empfänger trägt, den der Zustellweg nie annehmen könnte. Geprüft werden bei type: email die Schlüssel config.to und config.email, bei type: sms die Schlüssel config.to, config.phoneNumbers und config.phoneNumber; eine kommagetrennte Zeichenkette und ein Array gelten beide als Liste, jeder Eintrag wird geprüft, und die Meldung nennt den ersten beanstandeten Wert. Eine Mailadresse braucht genau ein @ mit Inhalt auf beiden Seiten und ohne Leerzeichen, die Form Name <adresse> ist erlaubt; eine SMS-Nummer muss E.164 sein: ein +, eine Ziffer 1-9, dann 7 bis 14 weitere Ziffern, ohne Leerzeichen, Bindestriche oder Klammern. Das sind die Regeln des Zustellwegs selbst, ein hier abgewiesener Wert hätte also nie einen Alarm empfangen. Ein Kanal OHNE eigenen Empfänger bleibt gültig: die Zustellung fällt dann auf die hinterlegte Adresse des Kunden oder der Organisation zurück. Geprüft werden nur email und sms; bei jedem anderen Typ bedeuten diese Schlüssel etwas anderes.
• 400 Bad Request mit data.code invalidRequestBody, wenn eine Ziel-URL in config keine parsebare http/https-URL ist oder auf eine private, Loopback- oder Link-Local-Adresse, auf localhost, auf einen reservierten Privatnamen (.local, .internal, .home.arpa) oder auf einen Hostnamen ohne Punkt zeigt. Als Ziel-URL gilt jede Zeichenkette der obersten config-Ebene, die mit http:// oder https:// beginnt; Felder mit Nachrichteninhalt (bodyTemplate, webhookBodyTemplate, headers) sind ausgenommen, ein Link ins eigene Netz ist dort berechtigt. Die Prüfung löst kein DNS auf; ein öffentlicher Name, der erst später privat auflöst, wird stattdessen bei der Zustellung gestoppt.
• 400 Bad Request wenn der Body die Validierung nicht besteht (unbekannter type, name mit mehr als 100 Zeichen, config ist kein JSON-Objekt, allowedPackageTypes ist kein Array)
• 400 Bad Request mit data.code: "configRequiredForTypeChange" wenn sich type ändert und keine config mitgeschickt wird
• 401 Unauthorized wenn du nicht authentifiziert bist
• 403 Forbidden wenn du auf Kanäle außerhalb deines Scopes zugreifst
• 404 Not found wenn der Kanal nicht existiert

Antwort (Response)Ankerlink kopieren

Gibt das aktualisierte Benachrichtigungskanal-Objekt zurück. Siehe Fehlercodes für Fehlerantworten.

BerechtigungenAnkerlink kopieren

Organisations-Admins schreiben Kanäle auf jeder Ebene. Ein kundengebundener Zugang (Rolle readonly) darf Kanäle anlegen, ändern und löschen, die an einen SEINER EIGENEN Kunden gebunden sind. Genau das bietet ihm die Integrationsseite im Dashboard an, während die API es bis zum 04.09.2026 mit einem nackten 403 verweigert hat.

Zwei Grenzen bleiben: Ein Kanal auf Organisationsebene, also ohne customerId, ist weiterhin Admins vorbehalten, und ein Kanal eines Kunden ausserhalb des eigenen Scopes wird abgelehnt wie bisher. Die Rollen editor und responder schreiben hier nicht.