Webhook — eventi di moderazione in tempo reale nei suoi sistemi

1Cosa fanno i webhook

Invece di interrogare l’API, registra un URL e Telm gli invia una POST HTTP firmata ogni volta che accade qualcosa nel suo gruppo. È così che porta gli eventi di moderazione nei suoi sistemi — una dashboard, un data warehouse, un canale di alerting — in tempo reale.

Gestisce gli endpoint webhook tramite l’API: registra un URL, sceglie a quali eventi iscriversi, li limita facoltativamente a gruppi specifici, invia un ping di prova e legge il registro delle consegne recenti.

2Perché il push batte il polling

Potrebbe chiamare l’endpoint del registro a intervalli per trovare nuovi eventi, ma questo aggiunge latenza, consuma quota e può mancare il momento esatto in cui qualcosa accade. I webhook ribaltano il modello: Telm le comunica l’istante in cui un evento scatta, così i suoi sistemi reagiscono in pochi secondi.

Usi tipici includono rispecchiare i ban nei suoi strumenti di amministrazione, avvisare un canale di team quando viene rilevato un raid, far confluire i rilevamenti nelle analytics, o innescare un flusso di lavoro quando un membro entra o esce.

• In tempo reale: viene a conoscenza di un evento nel momento in cui accade, non al polling successivo.
• Efficiente: nessuna lettura ripetuta che erode la sua quota giornaliera.
• Completo: le consegne vengono ritentate, così una breve interruzione dalla sua parte non perde eventi.

3Eventi a cui può iscriversi

Ci sono sette tipi di evento sottoscrivibili, che coprono verdetti di spam, punizioni e cambiamenti di appartenenza. Un singolo messaggio moderato può produrre più di un evento — un messaggio di spam che finisce in un ban emette sia spam.detected sia user.banned.

• spam.detected — il motore ha segnalato un messaggio come spam.
• message.suspicious — un rilevamento in ombra (modalità di monitoraggio) con un punteggio.
• user.banned — un membro è stato bannato.
• user.kicked — un membro è stato rimosso.
• user.muted — un membro è stato silenziato.
• user.joined — un membro è entrato nel gruppo.
• user.left — un membro ha lasciato il gruppo.

4L’involucro del payload

Ogni consegna è un involucro JSON con un piccolo e stabile insieme di campi di primo livello e un oggetto data specifico dell’evento all’interno. Può instradare sul tipo e sull’orario senza analizzare i dettagli finché non le servono.

• id — un id di consegna univoco; le riconsegne dello stesso evento riusano lo stesso id, ed è così che deduplica.
• type — il tipo di evento, uno dei sette sopra.
• created_at — quando l’evento è scattato, in RFC3339 UTC.
• group_id — il gruppo a cui l’evento appartiene (quando applicabile).
• data — un oggetto specifico dell’evento: dettagli del messaggio e del verdetto per gli eventi di spam, dettagli del membro per gli eventi di appartenenza.

5Verificare che le consegne provengano davvero da Telm

Ogni consegna è firmata così il suo server può confermare che la richiesta proviene davvero da Telm e non è stata manomessa in transito. Convalidi la firma prima di fidarsi del payload, e rifiuti tutto ciò che non corrisponde.

La firma è un HMAC-SHA256 del timestamp e del body grezzo della richiesta, con chiave il segreto di firma del suo endpoint. Per verificare, ricalcoli l’HMAC sull’header timestamp e sui byte esatti che ha ricevuto, e lo confronti con l’header della firma.

• X-Telm-Signature — la firma, formattata come v1 seguito dall’HMAC-SHA256 esadecimale del timestamp unito al body.
• X-Telm-Timestamp — il timestamp in secondi unix che viene firmato, così può rifiutare consegne stantie o riprodotte.
• X-Telm-Event — il tipo di evento, e X-Telm-Delivery — l’id di consegna per la deduplicazione.
• Il segreto di firma viene mostrato una sola volta quando crea l’endpoint e inizia con whsec_. Lo conservi in modo sicuro; è l’unica cosa che dimostra che una consegna è autentica.

6Consegna affidabile e deduplicata

La consegna è at-least-once: Telm garantisce che un evento la raggiunga, il che significa che lo stesso evento può occasionalmente arrivare due volte. Poiché ogni riconsegna riusa lo stesso id di consegna, deduplica memorizzando gli id che ha elaborato e saltando i doppioni.

Se il suo endpoint è irraggiungibile o restituisce un errore, la consegna viene ritentata secondo una pianificazione fissa — all’incirca dopo un minuto, cinque minuti, trenta minuti, due ore e sei ore, fino a sei tentativi in circa otto ore e mezza. Un endpoint che continua a fallire viene disabilitato automaticamente per proteggere entrambe le parti, e il proprietario viene avvisato.

• Risponda rapidamente con uno stato 2xx; svolga il lavoro pesante in modo asincrono dopo aver dato conferma.
• Deduplichi sull’id di consegna — mai sul contenuto del payload.
• Un endpoint che fallisce circa venti volte di fila senza successo entro una finestra di 72 ore viene auto-disabilitato; lo riabiliti una volta che il suo server è sano.

7Gestire gli endpoint e leggere il registro

Registra, modifica e rimuove gli endpoint webhook tramite l’API. Quando ne crea uno riceve il segreto di firma esattamente una volta, sceglie gli eventi a cui iscriversi e, facoltativamente, lo circoscrive a gruppi specifici. Una chiamata di prova invia un ping firmato così può confermare che la sua verifica funzioni prima che inizi il traffico reale.

Ogni endpoint mantiene un registro delle consegne che può rileggere per vedere cosa è stato inviato, quando e se ha avuto successo — comodo per il debug di un ricevitore senza attendere il prossimo evento dal vivo.

• Crei un endpoint e copi subito il segreto whsec_.
• Invii un ping di prova per convalidare il suo controllo di firma da capo a fondo.
• Circoscriva un endpoint a un gruppo o lo lasci aperto a tutti i gruppi che amministra.
• Legga il registro delle consegne per ispezionare i tentativi recenti e i loro esiti.

8Buone pratiche ed errori comuni

Un ricevitore robusto segue poche regole che prevengono i problemi più comuni.

• Verifichi la firma sui byte grezzi del body — analizzarlo prima in JSON e riserializzarlo può cambiare i byte e rompere il controllo.
• Restituisca 2xx rapidamente ed elabori dopo; un handler lento causa timeout e ritentativi inutili.
• Renda la gestione idempotente così un evento riconsegnato non viene contato due volte.
• Usi HTTPS su un URL pubblicamente raggiungibile; Telm blocca gli indirizzi interni e privati e non segue i redirect.
• Tenga il segreto whsec_ fuori dai log e dal codice client.