Integracja przez webhooki - przewodnik po wyzwalaczach HTTP

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:

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:

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:

{
  "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:

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.

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 czy Grafana
Monitoring dostępności: alerty o dostępności witryn i usług z Uptime Kuma lub 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 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
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
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.

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, 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, 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ę:

Do wstępnych testów użyj narzędzi takich jak curl, Postman albo klienta HTTP swojego języka
Zacznij od prostych szablonów i stopniowo dokładaj złożoność
Przetestuj obie metody, GET i POST, aby wybrać lepszą dla siebie
Sprawdź, czy znaki specjalne i Unicode są obsługiwane poprawnie
Przetestuj scenariusze błędów (brakujące zmienne, niepoprawny JSON), aby poznać zachowanie systemu
Na czas prac używaj kanałów testowych 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

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.

Rozwiązywanie problemów

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

Webhook nie wyzwala powiadomień

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
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)
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
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
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

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
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
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:

# 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 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 — twórz dynamiczne, treściwe powiadomienia
Używaj warunków — filtruj powiadomienia na podstawie danych
Przejrzyj integracje — połącz Echobell z narzędziami, których już używasz
Skonfiguruj alerty Grafany — monitoruj infrastrukturę
Skonfiguruj GitHub Actions — odbieraj powiadomienia z CI/CD
Wyzwalacze e-mail — 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!