Telm può inviare gli eventi di moderazione al suo server in tempo reale. Registra un endpoint, sceglie quali eventi ricevere e Telm invia un POST firmato per ciascuno. Ogni consegna trasporta una firma HMAC-SHA256 che verifica con il segreto del suo endpoint. Le consegne fallite vengono ritentate secondo una pianificazione; un endpoint irraggiungibile in modo permanente viene disattivato automaticamente.
1La busta dell'evento
Ogni webhook è un HTTP POST con un corpo JSON in una busta comune. La busta ha un id (un identificatore di consegna univoco per la deduplicazione), un type (il nome dell'evento), un timestamp created_at, il group_id a cui appartiene l'evento e un oggetto data la cui forma dipende dal tipo di evento.
L'id è deterministico per gli eventi reali, quindi se lo stesso evento viene consegnato due volte — per esempio dopo un ritentativo — riceve lo stesso id entrambe le volte. Usi l'header X-Telm-Delivery (che rispecchia questo id) come chiave di idempotenza così il suo gestore elabora ogni evento una sola volta.
- Campi della busta: id, type, created_at, group_id, data.
- type è uno dei nomi di evento del catalogo qui sotto.
- data trasporta i campi specifici dell'evento.
- Usa id (e l'header X-Telm-Delivery) per deduplicare i ritentativi.
2Catalogo degli eventi
Iscrivi un endpoint a un qualsiasi sottoinsieme del catalogo. spam.detected scatta quando il motore segnala un messaggio come spam. message.suspicious scatta in modalità di monitoraggio, quando il motore avrebbe agito ma ha solo assegnato un punteggio ombra al messaggio. Gli eventi sui membri coprono le persone che entrano, escono e vengono punite.
L'evento ping è speciale: non fa parte del catalogo sottoscrivibile e viene inviato solo quando attiva una consegna di prova per un endpoint, così può confermare che il suo ricevitore e il controllo della firma funzionino da un capo all'altro.
- spam.detected — un messaggio è stato classificato come spam.
- message.suspicious — un rilevamento ombra (modalità di monitoraggio).
- user.banned, user.kicked, user.muted — è stata applicata un'azione di moderazione.
- user.joined, user.left — un membro è entrato o uscito dal gruppo.
- ping — un evento di prova manuale, mai attivato da attività reale.
3Campi del payload per evento
Per spam.detected e message.suspicious, l'oggetto data trasporta message_id, user_id, username, il testo del messaggio (troncato per i messaggi molto lunghi), l'azione intrapresa, una category, una reason, la lingua rilevata e un punteggio di confidenza. message.suspicious trasporta inoltre il punteggio ombra.
Per gli eventi sui membri (user.joined, user.left, user.banned, user.kicked, user.muted), l'oggetto data trasporta user_id, username, first_name, un message_id facoltativo e una reason dove applicabile. Un singolo evento sottostante può produrre più di un webhook — un messaggio di spam che innesca un ban viene consegnato sia come spam.detected sia come user.banned.
- Eventi spam: message_id, user_id, username, text, action, category, reason, language, confidence (più score per message.suspicious).
- Eventi sui membri: user_id, username, first_name, message_id, reason.
- Un singolo incidente può emettere diversi eventi; correlali per user_id e group_id.
4Verificare la firma HMAC
Ogni consegna è firmata così può essere certo che provenga davvero da Telm e non sia stata manomessa. Ottenga un segreto dell'endpoint (inizia con whsec_) una sola volta, quando crea l'endpoint. Lo conservi e lo usi per verificare ogni richiesta in arrivo.
Per verificare, prenda il valore dell'header X-Telm-Timestamp, aggiunga un punto, poi aggiunga il corpo grezzo esatto della richiesta e calcoli un HMAC-SHA256 di quella stringa usando il segreto del suo endpoint come chiave. Codifichi il risultato in esadecimale e anteponga il prefisso v1= — deve essere uguale all'header X-Telm-Signature. Confronti con un confronto a tempo costante e rifiuti la richiesta se il timestamp è più vecchio di qualche minuto (cinque è una buona soglia) per bloccare i replay.
- X-Telm-Event — il tipo di evento.
- X-Telm-Delivery — l'id di consegna (chiave di idempotenza).
- X-Telm-Timestamp — secondi unix, firmati per prevenire i replay.
- X-Telm-Signature — v1= più l'HMAC-SHA256 esadecimale del timestamp, un punto e il corpo grezzo.
5Consegna, ritentativi e disattivazione automatica
Una consegna conta come riuscita solo se il suo endpoint risponde con uno stato 2xx. Qualsiasi altra cosa — un codice non 2xx, un timeout o un errore di connessione — viene trattata come un fallimento e ritentata secondo una pianificazione fissa: immediatamente, poi dopo 1 minuto, 5 minuti, 30 minuti, 2 ore e 6 ore, per sei tentativi che coprono all'incirca otto ore e mezza prima che la consegna venga chiusa come fallita.
Se un endpoint continua a fallire — almeno venti fallimenti consecutivi senza alcuna consegna riuscita per tre giorni — Telm lo disattiva automaticamente così smette di inviare a un URL morto. Può riabilitarlo dalla dashboard una volta che il suo ricevitore è di nuovo integro.
- Successo = HTTP 2xx. Rispondi in fretta (entro circa dieci secondi) ed esegui il lavoro pesante in modo asincrono.
- Pianificazione dei ritentativi: immediato, +1m, +5m, +30m, +2h, +6h (sei tentativi).
- Disattivato automaticamente dopo 20 fallimenti di fila senza alcun successo in 72 ore.
- La registrazione dei webhook richiede il piano Pro o superiore.