Telm může posílat moderační události na váš server v reálném čase. Zaregistrujete koncový bod, zvolíte, které události chcete přijímat, a Telm odešle podepsaný POST pro každou z nich. Každé doručení nese HMAC-SHA256 podpis, který ověříte pomocí tajemství svého koncového bodu. Neúspěšná doručení jsou opakována podle rozvrhu; trvale nedostupný koncový bod je automaticky vypnut.
1Obálka události
Každý webhook je HTTP POST s JSON tělem ve společné obálce. Obálka má id (jedinečný identifikátor doručení pro deduplikaci), type (název události), časové razítko created_at, group_id skupiny, ke které událost patří, a objekt data, jehož tvar závisí na typu události.
id je pro skutečné události deterministické, takže pokud je tatáž událost doručena dvakrát — například po opakování — obdržíte totéž id v obou případech. Použijte hlavičku X-Telm-Delivery (která toto id zrcadlí) jako idempotenční klíč, aby váš handler zpracoval každou událost pouze jednou.
- Pole obálky: id, type, created_at, group_id, data.
- type je jeden z názvů událostí z katalogu níže.
- data nese pole specifická pro událost.
- Použijte id (a hlavičku X-Telm-Delivery) k deduplikaci opakování.
2Katalog událostí
Koncový bod přihlásíte k libovolné podmnožině katalogu. spam.detected se spustí, když engine označí zprávu jako spam. message.suspicious se spustí v režimu monitorování, když by engine zareagoval, ale zprávu pouze stínově obodoval. Události členů pokrývají lidi vstupující, odcházející a trestané.
Událost ping je speciální: není součástí katalogu k přihlášení a odesílá se pouze tehdy, když spustíte testovací doručení pro koncový bod, abyste mohli od začátku do konce potvrdit, že váš příjemce a kontrola podpisu fungují.
- spam.detected — zpráva byla klasifikována jako spam.
- message.suspicious — stínová (monitorovací režim) detekce.
- user.banned, user.kicked, user.muted — byla uplatněna moderační akce.
- user.joined, user.left — člen vstoupil nebo opustil skupinu.
- ping — ruční testovací událost, nikdy nespuštěná skutečnou aktivitou.
3Pole payloadu podle události
Pro spam.detected a message.suspicious objekt data nese message_id, user_id, username, text zprávy (u velmi dlouhých zpráv zkrácený), provedenou akci, kategorii, důvod, detekovaný jazyk a skóre spolehlivosti. message.suspicious navíc nese stínové skóre.
Pro události členů (user.joined, user.left, user.banned, user.kicked, user.muted) objekt data nese user_id, username, first_name, volitelné message_id a důvod tam, kde se uplatní. Jedna základní událost může vyprodukovat více než jeden webhook — spamová zpráva, která spustí ban, je doručena jako spam.detected i user.banned.
- Spamové události: message_id, user_id, username, text, action, category, reason, language, confidence (plus score pro message.suspicious).
- Události členů: user_id, username, first_name, message_id, reason.
- Jediný incident může vyslat několik událostí; korelujte je podle user_id a group_id.
4Ověření HMAC podpisu
Každé doručení je podepsáno, abyste si mohli být jisti, že opravdu přišlo od Telm a nebylo pozměněno. Získáte tajemství koncového bodu (začíná whsec_) jednou, při vytvoření koncového bodu. Uložte ho a použijte k ověření každého příchozího požadavku.
Pro ověření vezměte hodnotu hlavičky X-Telm-Timestamp, připojte tečku, poté připojte přesné surové tělo požadavku a vypočtěte HMAC-SHA256 tohoto řetězce s použitím tajemství koncového bodu jako klíče. Výsledek zakódujte hexadecimálně a předsaďte mu v1= — musí se rovnat hlavičce X-Telm-Signature. Porovnávejte porovnáním s konstantním časem a odmítněte požadavek, pokud je časové razítko starší než pár minut (pět je dobrá hranice), abyste zablokovali opakování.
- X-Telm-Event — typ události.
- X-Telm-Delivery — id doručení (idempotenční klíč).
- X-Telm-Timestamp — unixové sekundy, podepsané pro zabránění opakování.
- X-Telm-Signature — v1= plus hexadecimální HMAC-SHA256 z časového razítka, tečky a surového těla.
5Doručení, opakování a automatické vypnutí
Doručení se počítá jako úspěšné pouze tehdy, když váš koncový bod odpoví stavem 2xx. Cokoli jiného — kód mimo 2xx, timeout nebo chyba připojení — je považováno za selhání a opakováno podle pevného rozvrhu: okamžitě, poté po 1 minutě, 5 minutách, 30 minutách, 2 hodinách a 6 hodinách, celkem šest pokusů rozprostřených zhruba přes osm a půl hodiny, než je doručení uzavřeno jako neúspěšné.
Pokud koncový bod stále selhává — nejméně dvacet po sobě jdoucích selhání bez úspěšného doručení po dobu tří dnů — Telm ho automaticky vypne, aby přestal odesílat na mrtvou URL. Můžete ho znovu zapnout z dashboardu, jakmile je váš příjemce opět v pořádku.
- Úspěch = HTTP 2xx. Odpovězte rychle (zhruba do deseti sekund) a náročnou práci provádějte asynchronně.
- Rozvrh opakování: okamžitě, +1m, +5m, +30m, +2h, +6h (šest pokusů).
- Automaticky vypnuto po 20 po sobě jdoucích selháních bez úspěchu za 72 hodin.
- Registrace webhooků vyžaduje tarif Pro nebo vyšší.