---
title: Integracja przez webhooki - przewodnik po wyzwalaczach HTTP
sidebarTitle: Webhooki
description: "Zintegruj webhooki Echobell: metody HTTP, zmienne, szablony, nagłówki i praktyczne przykłady natychmiastowych alertów na telefon."
---

# Integracja przez webhooki

Webhooki to najbardziej uniwersalny sposób wyzwalania powiadomień Echobell. Ten obszerny przewodnik obejmuje wszystko, co trzeba wiedzieć o wpinaniu alertów opartych na webhookach w Twoje systemy — od podstawowych pojęć po zaawansowane wzorce użycia.

## Czym jest webhook

Webhook to sposób, w jaki jedna aplikacja przekazuje innym aplikacjom informacje w czasie rzeczywistym, korzystając z wywołań zwrotnych HTTP. Pomyśl o nim jak o numerze telefonu, który komuś podajesz — gdy ktoś zadzwoni pod ten numer, Twój telefon dzwoni. W świecie cyfrowym, gdy w jednym systemie coś się dzieje (wysokie zużycie CPU, nieudany build, nowe zamówienie), wysyła on żądanie HTTP pod podany przez Ciebie adres URL (właśnie webhook), co uruchamia akcję w Twoim systemie.

Na przykład gdy zużycie CPU na serwerze zbytnio wzrośnie, system monitoringu może wywołać adres URL webhooka Echobell, który następnie wyśle powiadomienie z alertem. Dzieje się to automatycznie i w czasie rzeczywistym, bez potrzeby ciągłego sprawdzania obciążenia CPU na własną rękę.

Webhooki są fundamentem architektur sterowanych zdarzeniami i obsługuje je praktycznie każda nowoczesna usługa chmurowa, narzędzie monitorujące czy platforma SaaS. Są lekkie, szybkie i nie wymagają po Twojej stronie żadnej specjalnej infrastruktury — wystarczy klient HTTP.

### Zalety webhooków

- **Czas rzeczywisty**: zdarzenia wywołują powiadomienia natychmiast, zwykle w 1–2 sekundy
- **Uniwersalność**: obsługuje je niemal każda nowoczesna usługa i każdy język programowania
- **Elastyczność**: przekazuj własne dane, aby tworzyć bogate, kontekstowe powiadomienia
- **Niezawodność**: oparte na HTTP, ze standardowymi kodami statusu i obsługą błędów
- **Skalowalność**: bez odpytywania — powiadomienia idą tylko wtedy, gdy zdarzenie faktycznie wystąpi

## Przegląd

Każdy kanał Echobell można skonfigurować z unikalnym adresem URL webhooka. Gdy ten adres zostanie wywołany, kanał wysyła powiadomienia do wszystkich swoich subskrybentów, korzystając ze skonfigurowanych szablonów powiadomień i przekazanych zmiennych.

## Format adresu URL webhooka

```
https://hook.echobell.one/t/{channel-token}
```

Adres URL webhooka swojego kanału znajdziesz w widoku szczegółów kanału w aplikacji Echobell.

## Wysyłanie żądań do webhooka

Webhooki Echobell obsługują zarówno metodę GET, jak i POST:

### Żądanie GET

Zmienne możesz przekazać przez parametry zapytania:

```http
GET https://hook.echobell.one/t/<channel-token>?server_name=Production&cpu_usage=95
```

### Żądanie POST

Przy żądaniach POST wyślij zmienne w treści JSON:

```http
POST https://hook.echobell.one/t/<channel-token>
Content-Type: application/json

{
  "server_name": "Production",
  "cpu_usage": 95
}
```

### POST Only

Każdy kanał ma przełącznik **POST Only** w **Ustawieniach zaawansowanych** aplikacji Echobell. Domyślnie jest wyłączony.

Gdy jest włączony, kanał można wyzwolić wyłącznie metodą `POST`. Żądanie `GET` pod adres webhooka zostaje odrzucone z kodem `405 Method Not Allowed` i nie wysyła żadnego powiadomienia:

```json
{
  "success": false,
  "notificationTriggered": false,
  "message": "This trigger only accepts POST requests; GET triggering is disabled in its settings."
}
```

Żądania `HEAD` nie są objęte tym ustawieniem — zawsze odpowiadają kodem `200` i nigdy nie wyzwalają powiadomienia, niezależnie od tego, czy POST Only jest włączony.

Włącz je, jeśli adres URL webhooka trafia tam, gdzie odnośniki są pobierane automatycznie — do wiadomości na czacie, na stronę wiki, do paska adresu przeglądarki — aby podgląd lub otwarcie adresu nie uruchomiło alertu. Zostaw wyłączone, jeśli którykolwiek z Twoich systemów wyzwala kanał metodą `GET`.

## Zmienne specjalne

Echobell obsługuje specjalną zmienną, która rozszerza możliwości powiadomień:

- `externalLink`: dołączona do żądania tworzy klikalny odnośnik w widoku historii powiadomień. Przydaje się do odsyłania do szczegółowych informacji lub powiązanych zasobów.

Przykład z odnośnikiem zewnętrznym:

```http
POST https://hook.echobell.one/t/<channel-token>
Content-Type: application/json

{
  "server_name": "Production",
  "cpu_usage": 95,
  "externalLink": "https://dashboard.example.com/alerts/123"
}
```

## Zmienne szablonu

Zmiennych przekazanych przez webhook możesz używać w szablonach powiadomień w składni `{{variableName}}`:

```
Title: Server {{server_name}} Alert
Body: CPU usage has reached {{cpu_usage}}%
```

Po wyzwoleniu te szablony zostaną wypełnione wartościami przekazanymi w żądaniu webhooka.

## Systemowe zmienne czasu (UTC)

Poza danymi, które wysyłasz, Echobell udostępnia systemowe zmienne czasu tylko do odczytu, zawsze dostępne w szablonach i warunkach. Wszystkie wartości są wyliczane w strefie UTC. Wśród pól płaskich są `date`, `time`, `year`, `month`, `dayOfWeek`, `hour`, `minute` oraz `second`. Pozostałe — takie jak `sys.dayOfWeekName`, `sys.epochMs` czy `sys.epochSeconds` — są dostępne wyłącznie w przestrzeni nazw `sys.`. Pełną listę i przykłady znajdziesz w [warunkach](/docs/conditions).

## Typowe zastosowania

Webhooki są w Echobell najpopularniejszą metodą wyzwalania i sprawdzają się szczególnie przy:

### DevOps i monitoring
- **Monitoring serwerów**: alerty o CPU, pamięci i zajętości dysku z systemów takich jak [Prometheus](/docs/developer/prometheus) czy [Grafana](/docs/developer/grafana)
- **Monitoring dostępności**: alerty o dostępności witryn i usług z [Uptime Kuma](/docs/developer/uptime-kuma) lub [UptimeRobot](/docs/developer/uptimerobot)
- **Monitoring kontenerów**: awarie podów Dockera i Kubernetesa oraz ograniczenia zasobów
- **Agregacja logów**: krytyczne błędy i wyjątki z systemów zarządzania logami

### Programowanie i CI/CD
- **Powiadomienia o buildach**: nieudane buildy, wyniki testów i status wdrożeń z [GitHub Actions](/docs/developer/github) lub GitLab CI
- **Jakość kodu**: błędy lintera, podatności bezpieczeństwa, zmiany w pokryciu testami
- **Zdarzenia w repozytorium**: pull requesty, commity, wydania i aktywność współpracowników
- **Śledzenie wdrożeń**: udane wdrożenia, wycofania zmian i zmiany środowiska

### Aplikacje biznesowe
- **E-commerce**: nowe zamówienia, potwierdzenia płatności, ostrzeżenia o stanach magazynowych, aktualizacje wysyłek
- **CRM**: nowe leady, zamknięte transakcje, zgłoszenia do wsparcia, interakcje z klientami
- **Obsługa płatności**: zrealizowane transakcje, wnioski o zwrot, alerty o oszustwach
- **Formularze**: formularze kontaktowe, odpowiedzi w ankietach, ukończone rejestracje

### IoT i inteligentny dom
- **Zdarzenia w inteligentnym domu**: czujniki drzwi, wykrywanie ruchu, zmiany temperatury przez [Home Assistant](/docs/developer/home-assistant)
- **Urządzenia IoT**: odczyty czujników, zmiany stanu urządzeń, problemy z łącznością
- **Systemy bezpieczeństwa**: wyzwolenia alarmu, wykrycie ruchu przez kamerę, zdarzenia kontroli dostępu
- **Monitoring środowiska**: przekroczenia progów temperatury, wilgotności i jakości powietrza

### Trading i finanse
- **Alerty rynkowe**: ruchy cen i wskaźniki techniczne z [TradingView](/docs/trader/tradingview)
- **Monitoring portfela**: zmiany pozycji, wezwania do uzupełnienia depozytu, salda rachunków
- **Wydarzenia gospodarcze**: publikacje informacji, raporty wyników, zmiany nastrojów rynkowych

Instrukcje konfiguracji dla popularnych platform znajdziesz w naszych [przewodnikach po integracjach](/docs/features).

## Dobre praktyki

### Obsługa błędów
Nie polegaj wyłącznie na statusie HTTP — zawsze sprawdzaj treść odpowiedzi JSON i pole `success`:

- **200 OK**: żądanie zostało odebrane. Sprawdź treść JSON: `success: true` oznacza, że kanał został wyzwolony, a `success: false`, że żądanie przyjęto, lecz nie wysłano żadnego powiadomienia (na przykład przy nieznanym tokenie kanału, co i tak zwraca HTTP 200).
- **400 Bad Request**: token kanału ma niewłaściwą długość. Popraw adres URL webhooka.
- **405 Method Not Allowed**: kanał ma włączone [POST Only](#post-only), a żądanie nie było metodą `POST`. Przestaw system wywołujący na `POST` albo wyłącz to ustawienie.
- **500 Server Error**: chwilowy problem, ponów żądanie z wykładniczym odczekiwaniem

Echobell nie ogranicza częstotliwości wywołań webhooków, więc nie ma odpowiedzi `429`. Ponieważ nieznany (ale poprawnej długości) token wciąż zwraca `200` z `success: false`, zawsze podejmuj decyzje na podstawie pola `success` w JSON, a nie statusu HTTP.

### Ograniczanie częstotliwości
Stosuj rozsądne odstępy między wywołaniami webhooków, aby nie zalać własnego systemu powiadomień:

- Przy ciągłym monitoringu łącz wiele zdarzeń w jedno powiadomienie
- Używaj [warunków](/docs/conditions), aby odfiltrować zdarzenia niekrytyczne
- Rozważ agregowanie zdarzeń następujących szybko po sobie (np. wielu błędów w krótkim czasie)
- Unikaj wysyłania serii identycznych wyzwoleń, aby krytyczne alerty pozostały niezawodne

### Bezpieczeństwo danych
Adresy URL webhooków udostępniaj tylko zaufanym systemom i usługom:

- Traktuj adresy URL webhooków jak sekrety — dają bezpośrednią możliwość wysyłania powiadomień
- Nie umieszczaj ich w publicznych repozytoriach ani w publicznej dokumentacji
- Zmieniaj adresy URL webhooków okresowo oraz przy odejściu członków zespołu
- Skorzystaj z funkcji „Resetuj token” w kanale, aby unieważnić stare adresy, jeśli wyciekły
- Rozważ przechowywanie adresów w zmiennych środowiskowych lub w systemie zarządzania sekretami

### Nazewnictwo zmiennych
Stosuj jasne i spójne nazwy zmiennych w wywołaniach webhooków:

- Używaj nazw opisowych: `server_name` zamiast `s` czy `srv`
- Trzymaj się jednej konwencji nazewnictwa we wszystkich kanałach
- Udokumentuj, jakich zmiennych oczekują Twoje szablony
- Sprawdzaj przed wysłaniem, czy wszystkie wymagane zmienne są obecne

### Testowanie
Dokładnie przetestuj integrację z webhookiem, zanim wdrożysz ją na produkcję:

1. Do wstępnych testów użyj narzędzi takich jak `curl`, Postman albo klienta HTTP swojego języka
2. Zacznij od prostych szablonów i stopniowo dokładaj złożoność
3. Przetestuj obie metody, GET i POST, aby wybrać lepszą dla siebie
4. Sprawdź, czy znaki specjalne i Unicode są obsługiwane poprawnie
5. Przetestuj scenariusze błędów (brakujące zmienne, niepoprawny JSON), aby poznać zachowanie systemu
6. Na czas prac używaj [kanałów testowych](/docs) oddzielonych od produkcyjnych

### Projektowanie szablonów
Projektuj szablony tak, aby pozostawały użyteczne również wtedy, gdy brakuje zmiennych opcjonalnych:

- Zadbaj o wartości domyślne lub zastępcze dla danych opcjonalnych
- Buduj szablony tak, aby brak zmiennej nie psuł komunikatu
- Przetestuj szablony z różnymi kombinacjami obecnych i brakujących zmiennych
- Do sekcji opcjonalnych używaj [wyrażeń warunkowych](/docs/template)

### Monitorowanie
Monitoruj swoje integracje webhookowe, aby mieć pewność, że działają poprawnie:

- Loguj w swojej aplikacji udane i nieudane wywołania webhooków
- Śledź skuteczność dostarczania powiadomień i czasy odpowiedzi
- Skonfiguruj alerty na błędy webhooków lub nietypowe wzorce ruchu
- Okresowo przeglądaj i testuj kluczowe integracje webhookowe

## Prywatność i bezpieczeństwo

Jak Echobell postępuje z danymi z webhooków:

### Co jest przechowywane

- **Na naszych serwerach**: 
  - Adresy URL webhooków (tokeny) — potrzebne do kierowania przychodzących żądań do kanałów
  - Konfiguracje kanałów — szablony, warunki, ustawienia
  - Powiązania subskrypcji — kto subskrybuje które kanały
  
- **Na Twoim urządzeniu**:
  - Treść powiadomień — wyrenderowany tytuł i tekst treści
  - Historia wyzwoleń — kiedy powiadomienia dotarły
  - Wartości zmiennych — dane przekazane w wywołaniach webhooka
  - Odnośniki i metadane — `externalLink` i inne powiązane dane

### Czego nie przechowujemy

- Nie przechowujemy trwale surowych payloadów webhooków
- Nie logujemy ani nie zatrzymujemy danych wrażliwych z Twoich żądań
- Nie analizujemy ani nie przetwarzamy treści powiadomień w żadnym celu
- Nie udostępniamy danych z Twoich webhooków stronom trzecim

### Zalecenia dotyczące bezpieczeństwa

- **Traktuj adresy URL webhooków jak klucze API** — dają możliwość wysyłania powiadomień bez uwierzytelniania
- **Regularnie zmieniaj adresy** — użyj funkcji „Resetuj token”, aby wygenerować nowe adresy URL
- **Używaj klientów HTTPS** — przyjmujemy wyłącznie połączenia HTTPS, więc zadbaj, aby Twój klient weryfikował certyfikaty
- **Weryfikuj źródła webhooków** — w miarę możliwości ogranicz, które adresy IP lub usługi mogą wywoływać Twoje webhooki
- **Wypatruj nadużyć** — zwracaj uwagę na nietypowe wzorce i nieautoryzowane użycie
- **Rozdzielaj środowiska** — używaj osobnych kanałów dla środowiska deweloperskiego, staging i produkcji

Więcej informacji w [dokumentacji wsparcia](/docs/support).

## Rozwiązywanie problemów

Jeśli webhooki nie działają zgodnie z oczekiwaniami, wykonaj następujące kroki diagnostyczne:

### Webhook nie wyzwala powiadomień

1. **Sprawdź, czy adres URL webhooka jest poprawny**
   - Skopiuj adres bezpośrednio z aplikacji Echobell
   - Upewnij się, że nie doszły żadne dodatkowe spacje ani znaki
   - Sprawdź, czy używasz `https://hook.echobell.one/t/`, a nie innej domeny

2. **Sprawdź, czy kanał jest aktywny**
   - Otwórz kanał w aplikacji Echobell
   - Upewnij się, że nie został usunięty ani zarchiwizowany
   - Potwierdź, że token webhooka nie został zresetowany (to unieważniłoby adres URL)

3. **Upewnij się, że payload JSON jest poprawnie sformatowany** (przy żądaniach POST)
   - Sprawdź payload walidatorem JSON
   - Zadbaj o właściwe cudzysłowy wokół napisów
   - Sprawdź, czy nagłówek Content-Type ma wartość `application/json`

4. **Potwierdź, że przekazujesz wszystkie zmienne wymagane przez szablony**
   - Sprawdź w szablonach powiadomień, jakich zmiennych używają
   - Upewnij się, że te zmienne są w żądaniu webhooka (w parametrach zapytania lub treści JSON)
   - Pamiętaj, że brakujące zmienne wyrenderują się jako pusty ciąg

5. **Sprawdź, czy kanał ma aktywnych subskrybentów**
   - Powiadomienia są wysyłane tylko wtedy, gdy ktoś subskrybuje kanał
   - Zweryfikuj swoją subskrypcję na liście kanałów w aplikacji
   - Sprawdź, czy subskrypcje nie zostały przypadkiem usunięte

### Powiadomienia renderują się nieprawidłowo

1. **Nazwy zmiennych się nie zgadzają**
   - Szablon używa `{{server_name}}`, a webhook wysyła `serverName`
   - W nazwach zmiennych wielkość liter ma znaczenie i muszą zgadzać się dokładnie
   - Poszukaj literówek w nazwach zmiennych

2. **Brak dostępu do danych zagnieżdżonych**
   - Użyj notacji z kropką: `{{user.name}}` albo z nawiasami: `{{user["name"]}}`
   - Sprawdź, czy struktura JSON odpowiada temu, czego oczekuje szablon
   - Zacznij od prostych, płaskich zmiennych, a zagnieżdżenia dodaj później

3. **Problemy ze znakami specjalnymi**
   - Prawidłowo koduj parametry zapytania (URL-encode)
   - Poprawnie ekranuj znaki specjalne JSON w treściach żądań POST
   - Zacznij od prostego tekstu ASCII

### Testowanie integracji

Użyj `curl`, aby przetestować webhook bezpośrednio:

```bash
# Test z parametrami zapytania
curl "https://hook.echobell.one/t/<channel-token>?test=hello&status=working"

# Test z treścią JSON
curl -X POST https://hook.echobell.one/t/<channel-token> \
  -H "Content-Type: application/json" \
  -d '{"test": "hello", "status": "working"}'
```

Jeśli wszystko jest skonfigurowane poprawnie, powiadomienie powinno dotrzeć natychmiast.

### Problem nadal występuje?

Jeśli powyższe kroki nie pomogły:

- Zajrzyj do [centrum wsparcia](/docs/support) po dalsze wskazówki diagnostyczne
- Sprawdź, czy nie ma znanych problemów lub komunikatów o statusie usługi
- Napisz do nas na echobell@weelone.com i podaj:
  - Opis problemu
  - Kroki, które już wykonano
  - Przykładowy adres URL webhooka (z usuniętym lub zamaskowanym tokenem)
  - Przykładowy payload żądania
  - Zachowanie oczekiwane i faktyczne

## Kolejne kroki

Skoro wiesz już, jak działa integracja przez webhooki:

- **[Poznaj składnię szablonów](/docs/template)** — twórz dynamiczne, treściwe powiadomienia
- **[Używaj warunków](/docs/conditions)** — filtruj powiadomienia na podstawie danych
- **[Przejrzyj integracje](/docs/features)** — połącz Echobell z narzędziami, których już używasz
- **[Skonfiguruj alerty Grafany](/docs/developer/grafana)** — monitoruj infrastrukturę
- **[Skonfiguruj GitHub Actions](/docs/developer/github)** — odbieraj powiadomienia z CI/CD
- **[Wyzwalacze e-mail](/docs/email-trigger)** — alternatywna metoda wyzwalania dla systemów opartych na poczcie

Gotowe na integrację Echobell z Twoimi systemami? Utwórz swój pierwszy kanał i zacznij odbierać natychmiastowe powiadomienia!