Telm peut pousser les événements de modération vers votre serveur en temps réel. Vous enregistrez un endpoint, choisissez quels événements recevoir, et Telm envoie un POST signé pour chacun. Chaque livraison porte une signature HMAC-SHA256 que vous vérifiez avec le secret de votre endpoint. Les livraisons échouées sont réessayées selon un calendrier ; un endpoint définitivement injoignable est automatiquement désactivé.
1L’enveloppe de l’événement
Chaque webhook est un POST HTTP avec un corps JSON dans une enveloppe commune. L’enveloppe a un id (un identifiant de livraison unique pour la déduplication), un type (le nom de l’événement), un horodatage created_at, le group_id auquel appartient l’événement, et un objet data dont la forme dépend du type d’événement.
L’id est déterministe pour les vrais événements, si bien que si le même événement est livré deux fois — par exemple après un réessai — vous recevez le même id les deux fois. Utilisez l’en-tête X-Telm-Delivery (qui reflète cet id) comme clé d’idempotence afin que votre gestionnaire traite chaque événement une seule fois.
- Champs de l’enveloppe : id, type, created_at, group_id, data.
- type est l’un des noms d’événements du catalogue ci-dessous.
- data porte les champs spécifiques à l’événement.
- Utilisez id (et l’en-tête X-Telm-Delivery) pour dédupliquer les réessais.
2Catalogue des événements
Vous abonnez un endpoint à n’importe quel sous-ensemble du catalogue. spam.detected se déclenche quand le moteur signale un message comme spam. message.suspicious se déclenche en mode surveillance, quand le moteur aurait agi mais n’a fait que scorer le message en shadow. Les événements de membre couvrent les personnes qui entrent, partent et sont sanctionnées.
L’événement ping est spécial : il ne fait pas partie du catalogue auquel on peut s’abonner et n’est envoyé que lorsque vous déclenchez une livraison de test pour un endpoint, afin de confirmer que votre récepteur et votre vérification de signature fonctionnent de bout en bout.
- spam.detected — un message a été classé comme spam.
- message.suspicious — une détection en shadow (mode surveillance).
- user.banned, user.kicked, user.muted — une action de modération a été appliquée.
- user.joined, user.left — un membre est entré ou a quitté le groupe.
- ping — un événement de test manuel, jamais déclenché par une activité réelle.
3Champs de charge utile par événement
Pour spam.detected et message.suspicious, l’objet data porte message_id, user_id, username, le texte du message (tronqué pour les messages très longs), l’action prise, une category, une reason, la langue détectée, et un score de confidence. message.suspicious porte en plus le score shadow.
Pour les événements de membre (user.joined, user.left, user.banned, user.kicked, user.muted), l’objet data porte user_id, username, first_name, un message_id optionnel, et une reason là où elle s’applique. Un seul événement sous-jacent peut produire plus d’un webhook — un message de spam qui déclenche un bannissement est livré à la fois comme spam.detected et user.banned.
- Événements de spam : message_id, user_id, username, text, action, category, reason, language, confidence (plus score pour message.suspicious).
- Événements de membre : user_id, username, first_name, message_id, reason.
- Un seul incident peut émettre plusieurs événements ; corrélez-les par user_id et group_id.
4Vérifier la signature HMAC
Chaque livraison est signée afin que vous puissiez être certain qu’elle provient bien de Telm et n’a pas été altérée. Vous recevez un secret d’endpoint (il commence par whsec_) une seule fois, quand vous créez l’endpoint. Stockez-le et utilisez-le pour vérifier chaque requête entrante.
Pour vérifier, prenez la valeur de l’en-tête X-Telm-Timestamp, ajoutez un point, puis ajoutez le corps de requête brut exact, et calculez un HMAC-SHA256 de cette chaîne en utilisant le secret de votre endpoint comme clé. Encodez le résultat en hexadécimal et préfixez-le de v1= — il doit être égal à l’en-tête X-Telm-Signature. Comparez avec une comparaison à temps constant, et rejetez la requête si l’horodatage a plus de quelques minutes (cinq est un bon seuil) pour bloquer les rejeux.
- X-Telm-Event — le type d’événement.
- X-Telm-Delivery — l’id de livraison (clé d’idempotence).
- X-Telm-Timestamp — secondes unix, signées pour empêcher les rejeux.
- X-Telm-Signature — v1= plus le HMAC-SHA256 en hexadécimal de l’horodatage, un point, et le corps brut.
5Livraison, réessais et désactivation automatique
Une livraison ne compte comme réussie que si votre endpoint répond avec un statut 2xx. Tout le reste — un code non-2xx, un dépassement de délai, ou une erreur de connexion — est traité comme un échec et réessayé selon un calendrier fixe : immédiatement, puis après 1 minute, 5 minutes, 30 minutes, 2 heures et 6 heures, soit six tentatives couvrant environ huit heures et demie avant que la livraison ne soit close comme échouée.
Si un endpoint continue d’échouer — au moins vingt échecs consécutifs sans aucune livraison réussie pendant trois jours — Telm le désactive automatiquement afin qu’il cesse d’envoyer vers une URL morte. Vous pouvez le réactiver depuis le tableau de bord une fois que votre récepteur est de nouveau sain.
- Réussite = HTTP 2xx. Répondez vite (en une dizaine de secondes) et faites le travail lourd de façon asynchrone.
- Calendrier de réessais : immédiat, +1m, +5m, +30m, +2h, +6h (six tentatives).
- Désactivé automatiquement après 20 échecs d’affilée sans réussite en 72 heures.
- Enregistrer des webhooks nécessite le plan Pro ou supérieur.