Telm poate trimite evenimente de moderare către serverul dumneavoastră în timp real. Înregistrați un endpoint, alegeți ce evenimente să primiți, iar Telm trimite un POST semnat pentru fiecare. Fiecare livrare poartă o semnătură HMAC-SHA256 pe care o verificați cu secretul endpoint-ului dumneavoastră. Livrările eșuate sunt reîncercate după un program; un endpoint permanent inaccesibil este dezactivat automat.
1Plicul evenimentului
Fiecare webhook este un POST HTTP cu un corp JSON într-un plic comun. Plicul are un id (un identificator unic de livrare pentru deduplicare), un type (numele evenimentului), o marcă temporală created_at, group_id-ul căruia îi aparține evenimentul și un obiect data a cărui formă depinde de tipul evenimentului.
id-ul este determinist pentru evenimentele reale, deci dacă același eveniment este livrat de două ori — de exemplu după o reîncercare — primiți același id de ambele ori. Folosiți antetul X-Telm-Delivery (care reflectă acest id) ca cheie de idempotență astfel încât gestionarul dumneavoastră să proceseze fiecare eveniment o singură dată.
- Câmpurile plicului: id, type, created_at, group_id, data.
- type este unul dintre numele evenimentelor din catalogul de mai jos.
- data poartă câmpurile specifice evenimentului.
- Folosiți id (și antetul X-Telm-Delivery) pentru a deduplica reîncercările.
2Catalogul de evenimente
Abonați un endpoint la orice subset al catalogului. spam.detected se declanșează când motorul semnalează un mesaj ca spam. message.suspicious se declanșează în modul monitorizare, când motorul ar fi acționat, dar a punctat mesajul doar în umbră. Evenimentele de membru acoperă persoanele care intră, pleacă și sunt penalizate.
Evenimentul ping este special: nu face parte din catalogul la care vă puteți abona și este trimis doar când declanșați o livrare de test pentru un endpoint, astfel încât să puteți confirma că receptorul și verificarea semnăturii dumneavoastră funcționează cap la cap.
- spam.detected — un mesaj a fost clasificat ca spam.
- message.suspicious — o detectare în umbră (mod monitorizare).
- user.banned, user.kicked, user.muted — a fost aplicată o acțiune de moderare.
- user.joined, user.left — un membru a intrat sau a plecat din grup.
- ping — un eveniment de test manual, niciodată declanșat de activitate reală.
3Câmpurile sarcinii utile per eveniment
Pentru spam.detected și message.suspicious, obiectul data poartă message_id, user_id, username, textul mesajului (trunchiat pentru mesaje foarte lungi), acțiunea întreprinsă, o category, un reason, limba detectată și un scor de încredere. message.suspicious poartă suplimentar scorul din umbră.
Pentru evenimentele de membru (user.joined, user.left, user.banned, user.kicked, user.muted), obiectul data poartă user_id, username, first_name, un message_id opțional și un reason unde se aplică. Un singur eveniment de bază poate produce mai mult de un webhook — un mesaj de spam care declanșează o interdicție este livrat atât ca spam.detected, cât și ca user.banned.
- Evenimente de spam: message_id, user_id, username, text, action, category, reason, language, confidence (plus score pentru message.suspicious).
- Evenimente de membru: user_id, username, first_name, message_id, reason.
- Un singur incident poate emite mai multe evenimente; corelați-le după user_id și group_id.
4Verificarea semnăturii HMAC
Fiecare livrare este semnată astfel încât să puteți fi sigur că a venit cu adevărat de la Telm și nu a fost modificată. Primiți un secret al endpoint-ului (începe cu whsec_) o singură dată, când creați endpoint-ul. Păstrați-l și folosiți-l pentru a verifica fiecare cerere primită.
Pentru a verifica, luați valoarea antetului X-Telm-Timestamp, adăugați un punct, apoi adăugați corpul brut exact al cererii și calculați un HMAC-SHA256 al acelui șir folosind secretul endpoint-ului dumneavoastră ca cheie. Codificați rezultatul în hexazecimal și prefixați-l cu v1= — trebuie să fie egal cu antetul X-Telm-Signature. Comparați cu o comparație în timp constant și respingeți cererea dacă marca temporală este mai veche de câteva minute (cinci este un prag bun) pentru a bloca reluările.
- X-Telm-Event — tipul evenimentului.
- X-Telm-Delivery — id-ul livrării (cheie de idempotență).
- X-Telm-Timestamp — secunde unix, semnate pentru a preveni reluările.
- X-Telm-Signature — v1= plus HMAC-SHA256 în hexazecimal al mărcii temporale, un punct și corpul brut.
5Livrare, reîncercări și dezactivare automată
O livrare contează ca reușită doar dacă endpoint-ul dumneavoastră răspunde cu un status 2xx. Orice altceva — un cod non-2xx, un timeout sau o eroare de conexiune — este tratat ca un eșec și reîncercat după un program fix: imediat, apoi după 1 minut, 5 minute, 30 de minute, 2 ore și 6 ore, pentru șase încercări care se întind pe aproximativ opt ore și jumătate înainte ca livrarea să fie închisă ca eșuată.
Dacă un endpoint continuă să eșueze — cel puțin douăzeci de eșecuri consecutive fără nicio livrare reușită timp de trei zile — Telm îl dezactivează automat astfel încât să înceteze să trimită către un URL mort. Îl puteți reactiva din tabloul de bord odată ce receptorul dumneavoastră este din nou sănătos.
- Reușită = HTTP 2xx. Răspundeți rapid (în aproximativ zece secunde) și faceți munca grea asincron.
- Program de reîncercare: imediat, +1m, +5m, +30m, +2h, +6h (șase încercări).
- Dezactivat automat după 20 de eșecuri consecutive fără succes în 72 de ore.
- Înregistrarea webhook-urilor necesită planul Pro sau superior.