Webhooki — zdarzenia moderacji w czasie rzeczywistym w Twoich systemach

1Co robią webhooki

Zamiast odpytywać API, rejestrujesz adres URL, a Telm wysyła na niego podpisany HTTP POST za każdym razem, gdy coś dzieje się w Twojej grupie. Tak właśnie sprowadzasz zdarzenia moderacji do własnych systemów — panelu, hurtowni danych, kanału alertów — w czasie rzeczywistym.

Punktami końcowymi webhooków zarządzasz przez API: rejestrujesz adres URL, wybierasz, które zdarzenia subskrybować, opcjonalnie ograniczasz je do konkretnych grup, wysyłasz testowy ping i odczytujesz ostatni dziennik dostarczeń.

2Dlaczego wypychanie bije odpytywanie

Mógłbyś wywoływać punkt dziennika na timerze, aby znajdować nowe zdarzenia, ale to dodaje opóźnienie, zużywa przydział i może przegapić dokładny moment, gdy coś się dzieje. Webhooki odwracają model: Telm mówi Ci w chwili, gdy zdarzenie się uruchamia, więc Twoje systemy reagują w kilka sekund.

Typowe zastosowania to odzwierciedlanie banów we własnych narzędziach administracyjnych, alarmowanie kanału zespołu, gdy wykryto nalot, strumieniowanie wykryć do analiz albo uruchamianie procesu, gdy członek dołącza lub odchodzi.

• W czasie rzeczywistym: dowiadujesz się o zdarzeniu, gdy się dzieje, a nie przy kolejnym odpytaniu.
• Wydajnie: żadnych powtarzanych odczytów pochłaniających Twój dzienny przydział.
• Kompletnie: dostarczenia są ponawiane, więc krótka awaria po Twojej stronie nie gubi zdarzeń.

3Zdarzenia, które możesz subskrybować

Jest siedem subskrybowalnych typów zdarzeń, obejmujących werdykty spamu, kary i zmiany członkostwa. Jedna moderowana wiadomość może wygenerować więcej niż jedno zdarzenie — wiadomość spamowa, która kończy się banem, emituje zarówno spam.detected, jak i user.banned.

• spam.detected — silnik oflagował wiadomość jako spam.
• message.suspicious — wykrycie w cieniu (tryb monitorowania) z wynikiem.
• user.banned — członek został zbanowany.
• user.kicked — członek został usunięty.
• user.muted — członek został wyciszony.
• user.joined — członek dołączył do grupy.
• user.left — członek opuścił grupę.

4Koperta ładunku

Każde dostarczenie to koperta JSON z małym, stabilnym zestawem pól najwyższego poziomu oraz obiektem data zależnym od zdarzenia w środku. Możesz kierować ruchem na podstawie typu i czasu, bez parsowania szczegółów, dopóki ich nie potrzebujesz.

• id — unikalny identyfikator dostarczenia; ponowne dostarczenia tego samego zdarzenia używają tego samego id, i tak właśnie deduplikujesz.
• type — typ zdarzenia, jeden z siedmiu powyższych.
• created_at — kiedy zdarzenie się uruchomiło, w formacie RFC3339 UTC.
• group_id — grupa, do której należy zdarzenie (gdy ma to zastosowanie).
• data — obiekt zależny od zdarzenia: szczegóły wiadomości i werdyktu dla zdarzeń spamu, szczegóły członka dla zdarzeń członkostwa.

5Weryfikacja, że dostarczenia naprawdę pochodzą od Telm

Każde dostarczenie jest podpisane, aby Twój serwer mógł potwierdzić, że żądanie faktycznie pochodzi od Telm i nie zostało zmienione w tranzycie. Zweryfikuj podpis, zanim zaufasz ładunkowi, i odrzuć wszystko, co się nie zgadza.

Podpis to HMAC-SHA256 znacznika czasu i surowej treści żądania, kluczowany Twoim sekretem podpisującym punktu końcowego. Aby zweryfikować, przelicz ponownie HMAC z nagłówka znacznika czasu i dokładnych bajtów, które otrzymałeś, i porównaj go z nagłówkiem podpisu.

• X-Telm-Signature — podpis, sformatowany jako v1, po którym następuje szesnastkowy HMAC-SHA256 ze znacznika czasu połączonego z treścią.
• X-Telm-Timestamp — znacznik czasu w sekundach unix, który jest podpisywany, więc możesz odrzucać przeterminowane lub powtórzone dostarczenia.
• X-Telm-Event — typ zdarzenia, a X-Telm-Delivery — identyfikator dostarczenia do deduplikacji.
• Sekret podpisujący pokazywany jest raz, przy tworzeniu punktu końcowego, i zaczyna się od whsec_. Przechowuj go bezpiecznie; to jedyna rzecz, która dowodzi, że dostarczenie jest prawdziwe.

6Niezawodne, deduplikowane dostarczanie

Dostarczanie odbywa się co najmniej raz: Telm dba, by zdarzenie do Ciebie dotarło, co oznacza, że to samo zdarzenie może czasem przyjść dwa razy. Ponieważ każde ponowne dostarczenie używa tego samego identyfikatora dostarczenia, deduplikujesz, przechowując przetworzone identyfikatory i pomijając powtórzenia.

Jeśli Twój punkt końcowy jest nieosiągalny lub zwraca błąd, dostarczenie jest ponawiane według stałego harmonogramu — mniej więcej po jednej minucie, pięciu minutach, trzydziestu minutach, dwóch godzinach i sześciu godzinach, do sześciu prób w ciągu około ośmiu i pół godziny. Punkt końcowy, który wciąż zawodzi, jest automatycznie wyłączany, aby chronić obie strony, a właściciel jest powiadamiany.

• Odpowiadaj szybko statusem 2xx; ciężką pracę wykonuj asynchronicznie po potwierdzeniu.
• Deduplikuj po identyfikatorze dostarczenia — nigdy po zawartości ładunku.
• Punkt końcowy, który zawodzi około dwudziestu razy z rzędu bez powodzenia w oknie 72 godzin, jest automatycznie wyłączany; włącz go ponownie, gdy Twój serwer będzie sprawny.

7Zarządzanie punktami końcowymi i odczyt dziennika

Rejestrujesz, edytujesz i usuwasz punkty końcowe webhooków przez API. Gdy tworzysz jeden, otrzymujesz sekret podpisujący dokładnie raz, wybierasz zdarzenia do subskrypcji i opcjonalnie ograniczasz go do konkretnych grup. Wywołanie testowe wysyła podpisany ping, więc możesz potwierdzić, że Twoja weryfikacja działa, zanim zacznie się prawdziwy ruch.

Każdy punkt końcowy prowadzi dziennik dostarczeń, który możesz odczytać, aby zobaczyć, co wysłano, kiedy i czy się powiodło — przydatne do debugowania odbiorcy bez czekania na kolejne zdarzenie na żywo.

• Utwórz punkt końcowy i skopiuj sekret whsec_ natychmiast.
• Wyślij testowy ping, aby zweryfikować swoją kontrolę podpisu od początku do końca.
• Ogranicz punkt końcowy do jednej grupy albo pozostaw otwarty na wszystkie grupy, które administrujesz.
• Odczytaj dziennik dostarczeń, aby zbadać ostatnie próby i ich wyniki.

8Dobre praktyki i częste błędy

Solidny odbiorca stosuje kilka reguł, które zapobiegają najczęstszym problemom.

• Weryfikuj podpis na surowych bajtach treści — parsowanie do JSON i ponowna serializacja mogą zmienić bajty i zepsuć kontrolę.
• Zwracaj 2xx szybko, a przetwarzaj później; powolny handler powoduje przekroczenia limitu czasu i zbędne ponowienia.
• Uczyń obsługę idempotentną, aby ponownie dostarczone zdarzenie nie zliczyło się podwójnie.
• Używaj HTTPS na publicznie osiągalnym adresie URL; Telm blokuje adresy wewnętrzne i prywatne oraz nie podąża za przekierowaniami.
• Trzymaj sekret whsec_ z dala od dzienników i kodu klienta.