Powiadomienia Direct – osobiste klucze API do natychmiastowych alertów

Powiadomienia Direct pozwalają wysyłać osobiste alerty przez prosty adres URL webhooka — bez konfigurowania kanału, bez szablonów, bez subskrybentów. Wystarczy utworzyć klucz, wywołać adres URL i natychmiast dostać powiadomienie na urządzenie.

Czym jest Direct?

Kanały świetnie sprawdzają się przy uporządkowanych powiadomieniach opartych na szablonach, którymi można się dzielić z innymi. Czasem jednak chcesz po prostu szybkiego, osobistego powiadomienia — build się skończył, skrypt się wykonał, czujnik zadziałał. Direct powstał właśnie do tego.

W Direct dostajesz osobisty klucz API przypisany do unikalnego adresu URL webhooka. Gdy wywołasz ten adres z tytułem i treścią, powiadomienie trafi bezpośrednio do Ciebie. Konfigurowanie kanału jest zbędne.

Kiedy wybrać Direct, a kiedy kanały

Pierwsze kroki

1. Utwórz klucz Direct

W aplikacji Echobell dotknij Direct na górze listy kanałów. Następnie dotknij Utwórz, aby wygenerować nowy klucz Direct. Nadaj mu opisową nazwę (np. „Build Server”, „Home Lab”, „Trading Bot”).

2. Skopiuj adres URL webhooka

Każdy klucz Direct ma unikalny adres URL webhooka w tym formacie:

https://hook.echobell.one/d/{your-key-token}

Adres znajdziesz i skopiujesz w widoku szczegółów klucza Direct w aplikacji. Ze względów bezpieczeństwa token jest domyślnie ukryty — dotknij, aby go pokazać.

3. Wyślij powiadomienie

Wywołaj adres URL webhooka z ciałem JSON zawierającym pola title i body:

POST https://hook.echobell.one/d/YOUR_KEY_TOKEN
Content-Type: application/json

{
  "title": "Build Complete",
  "body": "Project X built successfully in 3m 42s"
}

To wszystko — powiadomienie otrzymasz natychmiast.

Wysyłanie żądań

Żądanie POST (zalecane)

Wyślij ciało JSON z treścią powiadomienia:

POST https://hook.echobell.one/d/YOUR_KEY_TOKEN
Content-Type: application/json

{
  "title": "Deployment Status",
  "body": "v2.1.0 deployed to production",
  "externalLink": "https://dashboard.example.com/deploys/latest"
}

Żądanie GET

Parametry możesz też przekazać w ciągu zapytania:

GET https://hook.echobell.one/d/YOUR_KEY_TOKEN?title=Alert&body=CPU+at+95%25

Tylko POST

Każdy klucz Direct ma własne ustawienie Tylko POST w aplikacji Echobell. Domyślnie jest wyłączone.

Gdy jest włączone, klucz może wyzwolić wyłącznie metoda POST. Żądanie GET na jego adres URL 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 działają bez zmian — odpowiadają kodem 200 i nigdy nie wyzwalają powiadomienia, niezależnie od tego, czy Tylko POST jest włączone, czy nie.

Ustawienie działa osobno dla każdego klucza, więc możesz trzymać jeden klucz przyjazny dla GET do jednolinijkowców w powłoce, a drugi tylko dla POST do adresów wklejanych na czacie czy stronach wiki.

Pola żądania

We wszystkich nazwach pól wielkość liter nie ma znaczenia — title, Title i TITLE są traktowane tak samo, niezależnie od tego, czy przekazujesz je w ciele JSON, czy w ciągu zapytania.

Typy powiadomień

Poziom pilności powiadomień Direct kontrolujesz polem notificationType:

Przykład z typem powiadomienia:

POST https://hook.echobell.one/d/YOUR_KEY_TOKEN
Content-Type: application/json

{
  "title": "Server Down",
  "body": "Production server is unresponsive",
  "notificationType": "calling"
}

Format odpowiedzi

Udane żądanie zwraca:

{
  "success": true,
  "message": "Notification triggered successfully."
}

Jeśli klucz jest nieprawidłowy lub nie został znaleziony (zwróć uwagę, że nadal zwracany jest kod HTTP 200):

{
  "success": false,
  "message": "Direct key not found."
}

Zarządzanie kluczami Direct

Wiele kluczy

Możesz utworzyć wiele kluczy Direct do różnych celów:

• „CI Server” — do powiadomień o buildach i wdrożeniach
• „Home Automation” — do alertów z czujników IoT
• „Cron Jobs” — do wyników zadań zaplanowanych
• „Trading Bot” — do alertów rynkowych

Każdy klucz ma własny, niezależny adres URL webhooka. Wpisy powiadomień są automatycznie powiązane z kluczem, który je wyzwolił, więc łatwo rozpoznasz, która usługa wysłała dane powiadomienie.

Reset tokenu

Jeśli adres URL webhooka danego klucza wyciekł, możesz zresetować token w widoku szczegółów klucza. Powstanie wtedy nowy adres URL, a stary natychmiast przestanie działać. Zaktualizuj wszystkie skrypty i usługi korzystające ze starego adresu.

Usuwanie klucza

Usunięcie klucza Direct trwale unieważnia jego adres URL webhooka. Wszystkie żądania na stary adres zakończą się niepowodzeniem.

Typowe zastosowania

Skrypty powłoki

# Notify when a long-running task finishes
./run-migration.sh && \
curl -X POST https://hook.echobell.one/d/YOUR_KEY_TOKEN \
  -H "Content-Type: application/json" \
  -d '{"title": "Migration Complete", "body": "Database migration finished successfully"}'

Zadania cron

# In crontab: notify on backup completion
0 2 * * * /usr/local/bin/backup.sh && curl -s -X POST https://hook.echobell.one/d/YOUR_KEY_TOKEN -H "Content-Type: application/json" -d '{"title": "Backup Done", "body": "Nightly backup completed"}'

Python

import requests

requests.post(
    "https://hook.echobell.one/d/YOUR_KEY_TOKEN",
    json={
        "title": "Training Complete",
        "body": f"Model accuracy: {accuracy:.2%}",
        "externalLink": "https://wandb.ai/runs/abc123"
    }
)

Node.js

await fetch("https://hook.echobell.one/d/YOUR_KEY_TOKEN", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    title: "Deploy Complete",
    body: `Version ${version} deployed to production`,
  }),
});

GitHub Actions

- name: Notify via Echobell Direct
  if: always()
  env:
    ECHOBELL_DIRECT_URL: ${{ secrets.ECHOBELL_DIRECT_URL }}
  run: |
    curl -X POST "$ECHOBELL_DIRECT_URL" \
      -H "Content-Type: application/json" \
      -d '{"title": "Build ${{ job.status }}", "body": "${{ github.repository }} @ ${{ github.sha }}"}'

Dobre praktyki

Bezpieczeństwo

• Traktuj adresy URL kluczy Direct jak sekrety — każdy, kto ma adres, może wysyłać Ci powiadomienia
• Używaj zmiennych środowiskowych do przechowywania tokenów kluczy w skryptach i CI/CD
• Resetuj tokeny natychmiast, gdy podejrzewasz, że klucz wyciekł
• Twórz osobne klucze dla różnych usług, aby móc unieważniać je pojedynczo

Organizacja

• Nadawaj kluczom opisowe nazwy — podziękujesz sobie, gdy będziesz zarządzać kilkoma naraz
• Używaj jednego klucza na usługę — łatwiej wtedy rozpoznać źródło powiadomienia i odebrać dostęp
• Usuwaj nieużywane klucze — zmniejszysz powierzchnię ataku

Obsługa błędów

Integrując Direct ze swoimi skryptami, opieraj logikę na polu success w JSON-ie, a nie na statusie HTTP:

• 200 OK: żądanie zostało odebrane. Sprawdź ciało JSON: success: true oznacza, że powiadomienie zostało wyzwolone, a success: false, że nie. Nieznany lub zresetowany klucz Direct zwraca HTTP 200 z { "success": false, "message": "Direct key not found." } — to nie jest 404.
• 400 Bad Request: token klucza ma nieprawidłową długość. Popraw adres URL.
• 405 Method Not Allowed: klucz ma włączone Tylko POST, a żądanie nie było metodą POST. Przestaw wywołanie na POST albo wyłącz to ustawienie.

Echobell nie ogranicza liczby wywołań Direct, więc odpowiedź 429 nie występuje.

Prywatność i bezpieczeństwo

Co jest przechowywane

• Na naszych serwerach:

  • Metadane kluczy Direct (nazwa, zahaszowany token, właściciel)
  • Payload żądania jest tymczasowo przetwarzany i przechowywany na potrzeby dostarczenia

• Na Twoim urządzeniu:

  • Treść powiadomień (tytuł, treść)
  • Historia wyzwoleń wraz ze znacznikami czasu
  • Odnośniki zewnętrzne

Czego nie przechowujemy

• Nie zatrzymujemy trwale payloadów żądań po dostarczeniu
• Nie analizujemy treści powiadomień
• Nie udostępniamy Twoich danych osobom trzecim

Rozwiązywanie problemów

Brak powiadomień

1. Sprawdź adres URL webhooka — skopiuj go bezpośrednio z aplikacji i upewnij się, że nie ma dodatkowych spacji
2. Sprawdź, czy klucz nadal istnieje — mógł zostać usunięty albo jego token zresetowany
3. Zadbaj o uprawnienia do powiadomień — aplikacja Echobell potrzebuje na Twoim urządzeniu zgody na powiadomienia
4. Przetestuj przez curl — aby wykluczyć problemy z Twoim klientem HTTP:

   curl -X POST https://hook.echobell.one/d/YOUR_KEY_TOKEN \
     -H "Content-Type: application/json" \
     -d '{"title": "Test", "body": "Hello from Direct"}'

Błędy żądań

• Błąd parsowania JSON: upewnij się, że ustawiony jest nagłówek Content-Type: application/json, a ciało jest poprawnym JSON-em
• Nie znaleziono klucza: odpowiedź z "success": false i komunikatem "Direct key not found." oznacza, że token został zresetowany albo klucz usunięty (status HTTP nadal wynosi 200)

Problem nadal występuje?

• Odwiedź nasze Centrum wsparcia, aby uzyskać więcej pomocy
• Napisz na echobell@weelone.com, podając:
  • Opis problemu
  • Przykładowe żądanie (z zamaskowanym tokenem)
  • Zachowanie oczekiwane i faktyczne

Kolejne kroki

• Integracja z webhookami — do współdzielonych powiadomień z szablonami i kanałami
• Składnia szablonów — poznaj szablony powiadomień w kanałach
• Wyzwalacze e-mail — wyzwalaj powiadomienia przez e-mail
• Przeglądaj integracje — połącz Echobell z narzędziami, których już używasz