TgWitness / Dokumentacja

Co zostało przetestowane →

Odniesienie / Archiwum i integracje

Telegram · Wychodzące webhooki

Wysyłaj zdarzenia z określonym zakresem do odbiorców HTTPS z podpisami HMAC, ponownymi próbami i statusem dostarczenia.

TgWitness / Dokumentacja · Integracje z archiwami

Integracje z archiwami

Przewodnik po procesie pracy · Wiki

W wybranym obszarze roboczym otwórz Więcej narzędzi → Integracje → Webhooki wychodzące. Dodaj odbiornik HTTPS, wybierz zdarzenia typu collector/media/export oraz opcjonalnie zaznacz czaty dla nowych obserwacji i zmian. Tekst wiadomości jest domyślnie wyłączony. Włączenie fragmentów dodaje maksymalnie 1,000 znaków do zdarzeń dotyczących zmian w wiadomościach; surowe pola Telegramu i dane uwierzytelniające nigdy nie są wysyłane.

Wprowadź klucz tajny HMAC jednorazowo do chronionej konfiguracji odbiorcy. Jest on zaszyfrowany w skarbcu TgWitness i nie można go odzyskać z panelu. Usuń i utwórz ponownie miejsce docelowe, aby je zmienić. Wyślij do syntetycznych kolejek testowych wiadomość bez treści czatu; odśwież status dostarczenia, aby sprawdzić wynik.

Dostarczanie rozszerza istniejącą pętlę powiadomień wraz z Apprise. Wykorzystuje trasę zewnętrzną obszaru roboczego oraz istniejące ograniczenia dotyczące prywatnych miejsc docelowych. Nie ma bezpośredniego rozwiązania awaryjnego ani przekierowania. Adresy URL nie mogą zawierać danych uwierzytelniających, ciągów zapytania ani fragmentów; adresy prywatne wymagają zgody na poziomie serwera, a nie ustawienia, które użytkownik panelu może ominąć.

Dane użytkowe i podpis#

Schemat: tgwitness.webhook/1. Każdy ładunek zawiera event_id, timestamp, workspace, type, synthetic oraz liczniki. Zdarzenia oparte na dzienniku zawierają swoją sekwencję i skrót. Zakończenie pełnego eksportu oraz testy syntetyczne są zdarzeniami dostarczenia, bez fikcyjnego odniesienia do podpisanego dziennika. Powiadomienia o usunięciu wiadomości w Telegramie oraz missing_on_recheck pozostają odrębnymi typami.

Nagłówek X-TgWitness-Signature to t=UNIX_SECONDS,v1=HEX_HMAC_SHA256. Oblicz HMAC dla dokładnych bajtów timestamp + "." + raw_request_body, używając wyświetlonego klucza tajnego jako bajtów w formacie UTF-8. Porównaj podpisy w stałym czasie przed przetworzeniem lub podjęciem działań na treści wiadomości. Odrzuć sygnatury czasowe, które różnią się o więcej niż pięć minut od czasu lokalnego. Sygnatura czasowa jest odświeżana przy każdej próbie dostarczenia wiadomości.

Należy używać event_id jako klucza idempotencji w trwałej pamięci, z atomowym ograniczeniem unikalności przed wystąpieniem efektów ubocznych. Sam prawidłowy podpis nie zapobiega ponownemu odtworzeniu ostatniego żądania. Przetworzone identyfikatory należy przechowywać co najmniej przez cały okres ponownych prób; należy je przechowywać dłużej, jeśli odbiorca może ponownie przetworzyć zapisane zdarzenia.

Ponowne próby#

Dostawy są trwale umieszczane w kolejce przed żądaniami HTTP. Wykorzystują one semantykę co najmniej raz : utracone potwierdzenie lub ponowne uruchomienie może spowodować ponowne dostarczenie zdarzenia o tym samym identyfikatorze. Przewidziano osiem prób z wykładniczym opóźnieniem, zaczynającym się od 15 sekund i ograniczonym do jednej godziny. Warunkiem powodzenia jest odpowiedź o kodzie 2xx. Zadanie, które wyczerpie limit ponownych prób, pozostaje widoczne wraz z błędem w celu weryfikacji.

Kolejka mieści 1 000 dostaw. Gdy jest pełna, skanowanie zdarzeń dziennika zostaje wstrzymane i wznowione po zwolnieniu miejsca. Zakończenie pełnego eksportu, którego nie można umieścić w kolejce, powoduje wyświetlenie widocznego błędu kolejki. W ramach każdego przebiegu powiadomień podejmowanych jest do pięciu prób wysłania, a zachowywanych jest 100 ostatnich zapisów prób. Usunięcie miejsca docelowego powoduje również usunięcie oczekujących wysyłek.

Przykład n8n#

Zaimportuj przykładowy przepływ pracy. Jest on nieaktywny i nie zawiera żadnych poufnych danych ani działań następczych. Ustaw TGWITNESS_WEBHOOK_SECRET w środowisku roboczym n8n, zezwól na dostęp do tego środowiska oraz zezwól na użycie wbudowanej funkcji crypto dla węzła Code. W przykładzie wykorzystano opcję raw-body węzła Webhook, sprawdzono podpis i aktualność oraz potwierdzono zweryfikowane zdarzenia. Jest to zgodne z udokumentowaną implementacją tego węzła.

Przed dodaniem zapisów lub powiadomień do systemu SIEM należy dodać trwałą pamięć idempotentną, indeksowaną za pomocą klucza event_id. Należy ograniczyć edycję przepływów pracy w n8n oraz okres przechowywania dzienników wykonania zgodnie z danymi, które zdecydowano się wysłać. TgWitness nie dodaje żadnych poleceń przychodzących.