Benachrichtigungskanal erstellen

POST /api/notification-channels

Anfrage (Request Body)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.

KanaltypenAnkerlink kopieren

Direkt (category: "direct"): email, sms, webhook.

Integrationen (category: "integration"): incident_management, slack, discord, teams, pagerduty, opsgenie, allquiet, telegram, googlechat, mattermost, rocketchat, matrix, lark, dingtalk, wecom, ilert, grafanaoncall, squadcast, incidentio, pushover, ntfy, gotify, jira, github, gitlab, linear, servicenow.

Die config-Felder hängen vom Typ ab: siehe Integrationen, was jeder Kanal benötigt. Du kannst einen Kanal vor dem Speichern mit dem Endpunkt Benachrichtigungskanal testen validieren.

incident_managementAnkerlink kopieren

Uptimeifys eigenes Incident Management ist ein Integrationskanal wie jeder andere, mit zwei Unterschieden:

• Er erwartet eine leere config ({}). Es gibt keinen Endpunkt und keine Zugangsdaten; bestätigte Ausfälle werden intern zugestellt.
• Er ist nicht testbar: der Endpunkt Benachrichtigungskanal testen unterstützt diesen Typ nicht.

Der Kanal steuert, welche Monitore über Incident Management alarmieren. Sein Geltungsbereich (customerId / websiteId, beide optional, beide weglassen für die gesamte Organisation) und seine allowedPackageTypes bestimmen, wessen bestätigte Ausfälle zu IM-Incidents werden; alles andere bleibt bei den klassischen Benachrichtigungen. Ein Monitoring-Ausfall erreicht Incident Management nur dann, wenn ein passender, aktiver Kanal existiert und das Paket des Kunden Integrations-Alarme erlaubt.

Beispiel (cURL): E-Mail-KanalAnkerlink kopieren

curl -X POST "$BASE_URL/api/notification-channels" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "email",
    "name": "Ops Email",
    "config": { "email": "ops@deinkunde.com", "to": "Ops Team <ops@deinkunde.com>" },
    "organizationId": 1
  }'

Beispiel (cURL): Slack-KanalAnkerlink kopieren

curl -X POST "$BASE_URL/api/notification-channels" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "slack",
    "name": "Alerts Slack Channel",
    "config": { "webhookUrl": "https://hooks.slack.com/services/T00/B00/xxx" },
    "organizationId": 1
  }'

Beispiel (cURL): Webhook-KanalAnkerlink kopieren

curl -X POST "$BASE_URL/api/notification-channels" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "webhook",
    "name": "Custom Webhook",
    "config": {
      "url": "https://deinkunde.com/webhook",
      "method": "POST",
      "headers": { "X-Custom-Header": "value" },
      "bodyTemplate": "{\"text\": \"{{websiteName}} is {{status}}\"}",
      "timeout": 30,
      "retryAttempts": 3,
      "retryDelay": 60,
      "expectedStatusCodes": "200,201,204"
    },
    "organizationId": 1
  }'

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 fehlt oder hat mehr als 100 Zeichen, config oder conditions ist kein JSON-Objekt (oder ein String, der sich nicht zu einem parsen lässt), delaySeconds außerhalb des Bereichs
• 401 Unauthorized wenn du nicht authentifiziert bist
• 403 Forbidden wenn du Kanäle für eine Organisation erstellst, für die du keine Schreibrechte hast
• 409 Conflict wenn bereits ein doppelter Website-Override existiert
• 409 Conflict mit data.code notificationChannelRecipientExists, wenn im selben Geltungsbereich bereits ein AKTIVER Kanal desselben Typs an dieselbe Adresse zustellt. Die Antwort nennt den vorhandenen Kanal in data.channelId. Ein wiederholter Anlege-Aufruf, dessen Antwort nie ankam, bekommt damit diesen Fehler statt eines zweiten Kanals; ein deaktivierter Kanal blockiert nie, und geprüft wird nicht der Name, sondern die Adresse.

Antwort (Response)Ankerlink kopieren

Gibt das erstellte 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.