Telm może wypychać zdarzenia moderacji na Twój serwer w czasie rzeczywistym. Rejestrujesz endpoint, wybierasz, które zdarzenia otrzymywać, a Telm wysyła podpisane POST dla każdego z nich. Każda dostawa niesie podpis HMAC-SHA256, który weryfikujesz sekretem endpointa. Nieudane dostawy są ponawiane według harmonogramu; trwale nieosiągalny endpoint jest automatycznie wyłączany.
1Koperta zdarzenia
Każdy webhook to żądanie HTTP POST z treścią JSON we wspólnej kopercie. Koperta ma id (unikalny identyfikator dostawy do deduplikacji), type (nazwę zdarzenia), znacznik czasu created_at, group_id, do której należy zdarzenie, oraz obiekt data, którego kształt zależy od typu zdarzenia.
id jest deterministyczne dla prawdziwych zdarzeń, więc jeśli to samo zdarzenie zostanie dostarczone dwa razy — na przykład po ponowieniu — otrzymasz to samo id za każdym razem. Użyj nagłówka X-Telm-Delivery (który odzwierciedla to id) jako klucza idempotencji, aby Twój handler przetworzył każde zdarzenie tylko raz.
- Pola koperty: id, type, created_at, group_id, data.
- type to jedna z nazw zdarzeń z katalogu poniżej.
- data niesie pola specyficzne dla zdarzenia.
- Użyj id (i nagłówka X-Telm-Delivery) do deduplikacji ponowień.
2Katalog zdarzeń
Subskrybujesz endpoint na dowolny podzbiór katalogu. spam.detected uruchamia się, gdy silnik oznaczy wiadomość jako spam. message.suspicious uruchamia się w trybie monitorowania, gdy silnik zadziałałby, ale jedynie ocenił wiadomość w cieniu. Zdarzenia członków obejmują osoby wchodzące, wychodzące i karane.
Zdarzenie ping jest szczególne: nie jest częścią subskrybowalnego katalogu i wysyłane jest tylko, gdy wyzwolisz dostawę testową dla endpointa, abyś mógł potwierdzić, że Twój odbiornik i sprawdzenie podpisu działają od początku do końca.
- spam.detected — wiadomość została sklasyfikowana jako spam.
- message.suspicious — wykrycie w cieniu (tryb monitorowania).
- user.banned, user.kicked, user.muted — zastosowano działanie moderacyjne.
- user.joined, user.left — członek wszedł lub opuścił grupę.
- ping — ręczne zdarzenie testowe, nigdy nie uruchamiane przez prawdziwą aktywność.
3Pola ładunku dla każdego zdarzenia
Dla spam.detected i message.suspicious obiekt data niesie message_id, user_id, username, tekst wiadomości (skrócony dla bardzo długich wiadomości), podjęte działanie, kategorię, powód, wykryty język i wynik pewności. message.suspicious dodatkowo niesie wynik cienia.
Dla zdarzeń członków (user.joined, user.left, user.banned, user.kicked, user.muted) obiekt data niesie user_id, username, first_name, opcjonalne message_id oraz powód, gdy ma zastosowanie. Jedno bazowe zdarzenie może wygenerować więcej niż jeden webhook — wiadomość spamowa wyzwalająca bana jest dostarczana zarówno jako spam.detected, jak i user.banned.
- Zdarzenia spamu: message_id, user_id, username, text, action, category, reason, language, confidence (plus score dla message.suspicious).
- Zdarzenia członków: user_id, username, first_name, message_id, reason.
- Pojedynczy incydent może wyemitować kilka zdarzeń; koreluj je po user_id i group_id.
4Weryfikacja podpisu HMAC
Każda dostawa jest podpisana, abyś mógł mieć pewność, że naprawdę pochodzi z Telm i nie została zmanipulowana. Dostajesz sekret endpointa (zaczyna się od whsec_) raz, gdy tworzysz endpoint. Przechowaj go i użyj do weryfikacji każdego przychodzącego żądania.
Aby zweryfikować, weź wartość nagłówka X-Telm-Timestamp, dołącz kropkę, a następnie dołącz dokładną surową treść żądania i oblicz HMAC-SHA256 tego ciągu, używając sekretu endpointa jako klucza. Zakoduj wynik szesnastkowo i poprzedź go v1= — musi być równy nagłówkowi X-Telm-Signature. Porównuj porównaniem o stałym czasie i odrzuć żądanie, jeśli znacznik czasu jest starszy niż kilka minut (pięć to dobra granica), aby blokować powtórzenia.
- X-Telm-Event — typ zdarzenia.
- X-Telm-Delivery — id dostawy (klucz idempotencji).
- X-Telm-Timestamp — sekundy uniksowe, podpisane, by zapobiec powtórzeniom.
- X-Telm-Signature — v1= plus szesnastkowy HMAC-SHA256 z znacznika czasu, kropki i surowej treści.
5Dostawa, ponowienia i automatyczne wyłączanie
Dostawa liczy się jako udana tylko, jeśli Twój endpoint odpowie statusem 2xx. Cokolwiek innego — kod inny niż 2xx, przekroczenie limitu czasu lub błąd połączenia — jest traktowane jako niepowodzenie i ponawiane według stałego harmonogramu: natychmiast, potem po 1 minucie, 5 minutach, 30 minutach, 2 godzinach i 6 godzinach, przez sześć prób obejmujących mniej więcej osiem i pół godziny, zanim dostawa zostanie zamknięta jako nieudana.
Jeśli endpoint wciąż zawodzi — co najmniej dwadzieścia kolejnych niepowodzeń bez żadnej udanej dostawy przez trzy dni — Telm automatycznie go wyłącza, tak by przestał wysyłać na martwy URL. Możesz go ponownie włączyć z panelu, gdy Twój odbiornik znów będzie sprawny.
- Sukces = HTTP 2xx. Odpowiadaj szybko (w około dziesięć sekund) i wykonuj ciężką pracę asynchronicznie.
- Harmonogram ponowień: natychmiast, +1min, +5min, +30min, +2godz, +6godz (sześć prób).
- Automatyczne wyłączenie po 20 kolejnych niepowodzeniach bez sukcesu w 72 godziny.
- Rejestrowanie webhooków wymaga planu Pro lub wyższego.