---
title: "Integracje powiadomień — API v1 i MCP | Nodea"
description: "Zarządzaj integracjami powiadomień (Slack, e-mail, Discord, MS Teams, Google Chat, webhook, PagerDuty, OpsGenie, SMS, Telegram) przez REST API v1 i serwer MCP. Scope'y alerting, maskowanie sekretów, testy powiadomień."
url: "https://nodea.pl/pl/dokumentacja-api/integrations"
lang: "pl"
updated: "2026-07-16"
---

# Integracje powiadomień — API v1 i MCP | Nodea

> Integracje powiadomień w Nodea zarządzasz programowo przez REST API v1 oraz serwer MCP. Sekrety (webhooki, klucze API) są zawsze maskowane w odpowiedziach, a odesłanie zamaskowanej wartości przy edycji nie nadpisuje zapisanego poświadczenia.

Integracje to **kanały powiadomień**, przez które Nodea informuje o awariach monitorowanych zasobów: Slack, e-mail, Discord, MS Teams, Google Chat, generyczny webhook, PagerDuty, OpsGenie, SMS oraz Telegram. Każda integracja należy do jednego użytkownika i przechowuje poświadczenia (URL webhooka, klucz API, adres e-mail, numer telefonu). Ten dokument opisuje **REST API v1** oraz **serwer MCP**, które pozwalają zarządzać integracjami programowo. Powiązane zasoby to [grupy powiadomień](https://nodea.pl/pl/dokumentacja-api/notification-groups) oraz [polityki eskalacji](https://nodea.pl/pl/dokumentacja-api/escalation-policies), które kierują alerty do tych kanałów.

## Uwierzytelnianie i wymagania

Wszystkie endpointy działają pod prefiksem /api/v1 (pełny przykład hosta: https://app.nodea.io/api/v1). Uwierzytelnianie odbywa się osobistym tokenem dostępu Passport w nagłówku Authorization: Bearer \<token\>. Limit zapytań: throttle:api-v1 = 240 żądań na minutę.

- **Scope'y:** odczyt = alerting:read, zapis = alerting:write, usuwanie = alerting:delete. alerting:write pokrywa tworzenie, aktualizację oraz akcje nienszczące (test, every-fail); alerting:delete obejmuje wyłącznie usuwanie.
- **Flaga funkcji:** trasy integracji wymagają włączonej flagi Pennant integrations.
- **Zakres właściciela:** integracja jest zawsze ograniczona do właściciela tokenu. Obcy lub nieznany identyfikator zwraca 404 (nigdy nie potwierdza istnienia zasobu innego użytkownika).
- **Błędy walidacji** → HTTP 422 z ciałem { "message": ..., "errors": { pole: \[..\] } }.

**Typy integracji:** slack, mail, telegram, discord, ms\_teams, google\_chat, webhook, pagerduty, opsgenie, sms. Każdy typ ma jeden kanoniczny klucz konfiguracji: slack → slack\_webhook\_url, mail → email\_address, discord → discord\_webhook\_url, ms\_teams → webhook\_url, google\_chat → google\_webhook\_url, webhook → webhook\_url, pagerduty → integration\_key, opsgenie → api\_key (plus opcjonalny region: us|eu), sms → phone\_number (E.164), telegram → chat\_id + integration\_code.

**Telegram jest tylko dla interfejsu WWW.** Konfiguracja Telegrama to interaktywny proces parowania bota (przekierowanie do telegram.me z jednorazowym integration\_code), którego klient headless nie potrafi ukończyć. Dlatego tworzenie i edycja Telegrama przez API/MCP są odrzucane — obsługiwane są tylko odczyt, test i usunięcie.

## Maskowanie sekretów — najważniejsza zasada

**Poświadczenia NIGDY nie wracają w postaci jawnej.** Każda odpowiedź (API i MCP) przechodzi przez IntegrationResource, które maskuje wszystkie klucze sekretów: slack\_webhook\_url, discord\_webhook\_url, webhook\_url, google\_webhook\_url, integration\_key, api\_key, integration\_code. Format maski: \*\*\*\* + ostatnie 4 znaki; sekrety o długości 8 znaków lub krótsze zwijają się do samego \*\*\*\* (maska nigdy nie ujawnia połowy krótkiego poświadczenia). Klucze routingowe pozostają czytelne: email\_address, phone\_number, chat\_id (Telegram — bezużyteczny bez tokenu bota), region (wybór centrum danych OpsGenie).

**Odesłanie zamaskowanej wartości przy aktualizacji = brak zmiany.** Przy PATCH/PUT wartości sekretów, które przychodzą puste lub zamaskowane (zaczynają się od \*\*\*\*), są usuwane PRZED walidacją. Dzięki temu pobranie integracji i odesłanie jej z powrotem jest dla sekretu operacją pustą (zostaje zapisane oryginalne poświadczenie), a maska nigdy nie trafia na regułę url pola webhooka. Aby wymienić sekret, przekaż pełną nową wartość.

## API v1

MetodaŚcieżkaScopeOpisGET/integrationsalerting:readLista integracji (filtry: type, search; sort, paginacja).GET/integrations/{integration}alerting:readPojedyncza integracja.POST/integrationsalerting:writeUtworzenie integracji.PATCH / PUT/integrations/{integration}alerting:writeCzęściowa aktualizacja (typ niezmienny, Telegram odrzucany).DELETE/integrations/{integration}alerting:deleteTrwałe usunięcie (204 No Content).POST/integrations/{integration}/testalerting:writeWysłanie testowego powiadomienia.POST/integrations/{integration}/every-failalerting:writePrzełączenie flagi every\_fail.

### Kształt odpowiedzi

Każdy zasób integracji zawiera pola: id, name, type, every\_fail (bool), is\_ready (bool — czy poświadczenia są gotowe do wysyłki), config (obiekt z zamaskowanymi sekretami), created\_at, updated\_at (ISO 8601) oraz health (obiekt stanu dostarczania — patrz niżej).

### Stan zdrowia (health)

Każdy zasób zawiera obiekt health opisujący, czy powiadomienia przez integrację są dostarczane. Stan aktualizuje się automatycznie przy każdej próbie wysyłki; nie można go ustawić przez API.

- status — healthy (działa), failing (ostatnie dostarczenia się nie powiodły, alerty są nadal wysyłane) albo suspended (błędy utrzymywały się, więc wysyłka alertów przez tę integrację jest **wstrzymana**).
- consecutive\_failures (int) — liczba nieudanych dostarczeń od ostatniego sukcesu.
- first\_failure\_at, last\_failure\_at, last\_success\_at, suspended\_at — ISO 8601 albo null. last\_success\_at odświeża się najwyżej co 15 minut.
- next\_probe\_at — termin następnego automatycznego sprawdzenia wstrzymanej integracji (tylko gdy status = suspended, inaczej null). null przy wstrzymanej integracji oznacza, że sprawdzanie zostało zatrzymane.
- probe\_attempts (int) — liczba nieudanych sprawdzeń od chwili wstrzymania.
- last\_error — krótki opis ostatniego błędu (maks. 500 znaków, adres URL skrócony do hosta, sekrety usunięte) albo null dla działającej integracji.
- last\_error\_kind — permanent (np. HTTP 404, cofnięty token) | transient (timeout, 5xx) | null.
- auto\_probe (bool) — czy wstrzymana integracja jest sprawdzana automatycznie. false dla pagerduty, opsgenie i sms (wiadomość testowa otworzyłaby prawdziwy incydent lub kosztowała) — te typy wznawia się zapisem poprawionej konfiguracji.
- manual\_test\_supported (bool) — czy dla typu działa POST /integrations/{integration}/test.

**Wznowienie wysyłki:** udany test (POST …/test, narzędzie MCP integration-test), zapis konfiguracji (PATCH/PUT, integration-update) albo udane automatyczne sprawdzenie przywraca status = healthy.

"health": { "status": "suspended", "consecutive\_failures": 6, "first\_failure\_at": "2026-10-11T08:12:04+00:00", "last\_failure\_at": "2026-10-11T09:40:51+00:00", "last\_success\_at": "2026-10-10T22:03:17+00:00", "suspended\_at": "2026-10-11T09:40:51+00:00", "next\_probe\_at": "2026-10-11T10:10:51+00:00", "probe\_attempts": 0, "last\_error": "DeliveryFailedException: Webhook responded with HTTP 404.", "last\_error\_kind": "permanent", "auto\_probe": true, "manual\_test\_supported": true }

### GET /integrations — lista

Parametry zapytania: search (string, max 255 — dopasowanie po nazwie i typie), type (jeden z typów integracji), sort (name|type|created\_at), direction (asc|desc), per\_page (1–100, domyślnie 20), page. Odpowiedź jest paginowana (koperta data + meta/links).

curl -s https://app.nodea.io/api/v1/integrations?type=slack&per\_page=20 \\ -H "Authorization: Bearer $TOKEN" \\ -H "Accept: application/json"

### POST /integrations — utworzenie

Ciało: name (wymagane, max 100), type (wymagane; telegram odrzucany z 422), every\_fail (opcjonalne, bool), oraz kanoniczny klucz konfiguracji dla wybranego typu (patrz tabela typów wyżej). Reguły konfiguracji są per-typ: URL-e webhooków muszą być poprawnymi, bezpiecznymi publicznymi adresami; email\_address waliduje się przez email:rfc,dns; phone\_number musi być w formacie E.164 (+ i 7–15 cyfr); integration\_key/api\_key mają min. 10 znaków.

Kody błędów tworzenia: 402 z { "code": "plan\_limit\_exceeded" } gdy plan wyczerpał limit integracji; 422 z { "code": "missing\_config" } gdy brakuje wymaganego klucza konfiguracji dla wybranego typu. Sukces zwraca 201 Created z zamaskowanym zasobem.

curl -s -X POST https://app.nodea.io/api/v1/integrations \\ -H "Authorization: Bearer $TOKEN" \\ -H "Content-Type: application/json" \\ -H "Accept: application/json" \\ -d '{ "name": "Ops Slack", "type": "slack", "every\_fail": false, "slack\_webhook\_url": "https://hooks.slack.com/services/T000/B000/XXXX" }'

### PATCH /integrations/{integration} — aktualizacja

Aktualizacja jest częściowa: pomijane pola pozostają bez zmian. type jest **niezmienny** (reguła prohibited — zmiana dostawcy osierociłaby zapisaną konfigurację; utwórz nową integrację). Integracje telegram są odrzucane z 422 i { "code": "telegram\_not\_supported" }. Zamaskowane lub puste sekrety są ignorowane (patrz sekcja [Maskowanie sekretów](#maskowanie)).

curl -s -X PATCH https://app.nodea.io/api/v1/integrations/42 \\ -H "Authorization: Bearer $TOKEN" \\ -H "Content-Type: application/json" \\ -H "Accept: application/json" \\ -d '{ "name": "Ops Slack (prod)", "every\_fail": true }'

### POST /integrations/{integration}/test — test powiadomienia

Wysyła testowe powiadomienie tym samym serwisem, którego używa interfejs WWW. Obsługiwane typy: slack, mail, telegram, ms\_teams, discord, google\_chat. Pozostałe typy (webhook, pagerduty, opsgenie, sms) zwracają 422 z { "code": "test\_not\_supported" }.

**Ochrona przed danymi seedera:** jeśli integracja przechowuje poświadczenia zastępcze (słownictwo seedera), test zwraca 422 z { "code": "placeholder\_credentials" } BEZ wysyłania czegokolwiek do zewnętrznego API. Gdy dostawca odrzuci wysyłkę (zły webhook, cofnięty token), zwracane jest 502 z { "code": "test\_failed", "reason": ... }. Sukces: { "message": "Test notification sent." }. Udany test zdejmuje wstrzymanie integracji (health.status wraca do healthy) bez wysyłania maila.

curl -s -X POST https://app.nodea.io/api/v1/integrations/42/test \\ -H "Authorization: Bearer $TOKEN" \\ -H "Accept: application/json"

### POST /integrations/{integration}/every-fail — flaga every\_fail

Ciało: enabled (wymagane, bool). true = powiadomienie przy KAŻDYM nieudanym teście; false = tylko przy zmianach stanu (awaria/przywrócenie). Zwraca zaktualizowany zasób.

curl -s -X POST https://app.nodea.io/api/v1/integrations/42/every-fail \\ -H "Authorization: Bearer $TOKEN" \\ -H "Content-Type: application/json" \\ -H "Accept: application/json" \\ -d '{ "enabled": true }'

### Kody błędów

- 401 — brak lub nieprawidłowy token.
- 403 — token bez wymaganego scope'u.
- 404 — integracja nie istnieje lub należy do innego użytkownika.
- 422 — błąd walidacji (lub missing\_config, telegram\_not\_supported, placeholder\_credentials, test\_not\_supported).
- 402 — przekroczony limit planu przy tworzeniu (plan\_limit\_exceeded).
- 502 — dostawca odrzucił test (test\_failed).

## MCP

Serwer MCP udostępnia 7 narzędzi do zarządzania integracjami. Wszystkie wymagają włączonej flagi integrations i odpowiedniego scope'u. Sekrety są maskowane identycznie jak w API. Narzędzia oznaczone jako **destrukcyjne** wymagają jawnego confirm: true.

NazwaScopeTrybOpisintegrations-listalerting:readread-onlyLista integracji użytkownika (filtr type, search, paginacja).integration-getalerting:readread-onlyPojedyncza integracja po id.integration-createalerting:writezapisUtworzenie integracji (Telegram niedozwolony).integration-updatealerting:writezapisCzęściowa aktualizacja (typ niezmienny, Telegram niedozwolony).integration-testalerting:writezapisWysłanie testowego powiadomienia.integration-set-every-failalerting:writezapisPrzełączenie flagi every\_fail.integration-deletealerting:deletedestrukcyjnyTrwałe usunięcie — wymaga confirm: true.

### integrations-list

Parametry: type (opcjonalny filtr typu), search (opcjonalny fragment nazwy), page (min 1), per\_page (1–50, domyślnie 15). Zwraca data (zamaskowane integracje, każda z obiektem health jak w API) + meta (paginacja). integration-get zwraca ten sam kształt dla jednej integracji.

{ "method": "tools/call", "params": { "name": "integrations-list", "arguments": { "type": "slack", "per\_page": 15 } } }

### integration-create

Parametry: name (wymagane), type (wymagane; Telegram wykluczony z enuma), config (wymagany obiekt z kluczem poświadczenia dla typu), every\_fail (domyślnie false). Ten sam limit planu (create-integration) co w API.

{ "method": "tools/call", "params": { "name": "integration-create", "arguments": { "name": "Ops Slack", "type": "slack", "config": { "slack\_webhook\_url": "https://hooks.slack.com/services/T000/B000/XXXX" } } } }

### integration-update

Parametry: id (wymagane), oraz opcjonalnie name, config, every\_fail. Przekazanie zamaskowanej wartości konfiguracji (\*\*\*\*..., tak jak zwracają ją narzędzia odczytu) zachowuje zapisany sekret; przekaż pełną nową wartość, aby go wymienić.

{ "method": "tools/call", "params": { "name": "integration-update", "arguments": { "id": 42, "config": { "slack\_webhook\_url": "\*\*\*\*XXXX" }, "every\_fail": true } } }

### integration-test

Parametry: id (wymagane). Poświadczenia zastępcze (seeder) są odrzucane bez dotknięcia zewnętrznego API. Typy bez wysyłacza testu (webhook, pagerduty, opsgenie, sms) zwracają jawny błąd (interfejs WWW nie oferuje dla nich przycisku testu). Udany test zdejmuje wstrzymanie integracji.

{ "method": "tools/call", "params": { "name": "integration-test", "arguments": { "id": 42 } } }

### integration-delete (destrukcyjne)

Parametry: id (wymagane) oraz confirm (wymagane, musi być true). Bez confirm: true usunięcie jest odrzucane, aby agent nie skasował integracji na luźno zinterpretowanej instrukcji. Grupy powiadomień i kroki eskalacji odwołujące się do niej tracą ten kanał. Operacja jest nieodwracalna.

{ "method": "tools/call", "params": { "name": "integration-delete", "arguments": { "id": 42, "confirm": true } } }

## Powiązane

- [Grupy powiadomień — API v1 i narzędzia MCP | Nodea](https://nodea.pl/pl/dokumentacja-api/notification-groups)
- [Polityki eskalacji — API v1 i MCP | Nodea](https://nodea.pl/pl/dokumentacja-api/escalation-policies)

---

Wersje językowe: [en](https://nodea.io/en/api-docs/integrations.md)  
Spis treści witryny: [llms.txt](https://nodea.pl/pl/llms.txt)