Webhooks — les événements de modération en temps réel dans vos systèmes

1Ce que font les webhooks

Au lieu d’interroger l’API, vous enregistrez une URL et Telm y envoie un POST HTTP signé chaque fois que quelque chose se produit dans votre groupe. C’est ainsi que vous faites entrer les événements de modération dans vos propres systèmes — un tableau de bord, un entrepôt de données, un canal d’alerte — en temps réel.

Vous gérez les endpoints de webhook via l’API : enregistrer une URL, choisir à quels événements vous abonner, éventuellement les limiter à des groupes précis, envoyer un ping de test, et lire le journal des livraisons récentes.

2Pourquoi pousser vaut mieux qu’interroger

Vous pourriez appeler l’endpoint du journal à intervalle régulier pour trouver de nouveaux événements, mais cela ajoute de la latence, dépense du quota, et peut rater l’instant exact où quelque chose se produit. Les webhooks inversent le modèle : Telm vous prévient à l’instant où un événement se déclenche, si bien que vos systèmes réagissent en quelques secondes.

Les usages typiques incluent la réplication des bannissements dans vos propres outils d’administration, l’alerte d’un canal d’équipe quand un raid est détecté, la diffusion des détections vers l’analytique, ou le déclenchement d’un workflow quand un membre rejoint ou part.

• Temps réel : vous apprenez un événement au moment où il se produit, pas à votre prochaine interrogation.
• Efficace : pas de lectures répétées qui grignotent votre quota quotidien.
• Complet : les livraisons sont réessayées, si bien qu’une brève panne de votre côté ne perd pas d’événements.

3Événements auxquels vous pouvez vous abonner

Il existe sept types d’événements auxquels s’abonner, couvrant les verdicts de spam, les sanctions et les changements d’adhésion. Un seul message modéré peut produire plus d’un événement — un message de spam qui se termine par un bannissement émet à la fois spam.detected et user.banned.

• spam.detected — le moteur a signalé un message comme spam.
• message.suspicious — une détection fantôme (mode surveillance) avec un score.
• user.banned — un membre a été banni.
• user.kicked — un membre a été retiré.
• user.muted — un membre a été rendu muet.
• user.joined — un membre a rejoint le groupe.
• user.left — un membre a quitté le groupe.

4L’enveloppe de la charge utile

Chaque livraison est une enveloppe JSON avec un petit ensemble stable de champs de premier niveau et un objet data spécifique à l’événement à l’intérieur. Vous pouvez router sur le type et l’heure sans analyser les détails tant que vous n’en avez pas besoin.

• id — un id de livraison unique ; les relivraisons du même événement réutilisent le même id, c’est ainsi que vous dédupliquez.
• type — le type d’événement, l’un des sept ci-dessus.
• created_at — quand l’événement s’est déclenché, en RFC3339 UTC.
• group_id — le groupe auquel l’événement appartient (le cas échéant).
• data — un objet spécifique à l’événement : détails du message et du verdict pour les événements de spam, détails du membre pour les événements d’adhésion.

5Vérifier que les livraisons viennent vraiment de Telm

Chaque livraison est signée pour que votre serveur puisse confirmer que la requête vient réellement de Telm et n’a pas été altérée en transit. Validez la signature avant de faire confiance à la charge utile, et rejetez tout ce qui ne correspond pas.

La signature est un HMAC-SHA256 de l’horodatage et du corps brut de la requête, avec pour clé votre secret de signature d’endpoint. Pour vérifier, recalculez le HMAC sur l’en-tête d’horodatage et les octets exacts que vous avez reçus, et comparez-le à l’en-tête de signature.

• X-Telm-Signature — la signature, au format v1 suivi du HMAC-SHA256 hexadécimal de l’horodatage joint au corps.
• X-Telm-Timestamp — l’horodatage en secondes unix qui est signé, pour que vous puissiez rejeter les livraisons périmées ou rejouées.
• X-Telm-Event — le type d’événement, et X-Telm-Delivery — l’id de livraison pour la déduplication.
• Le secret de signature n’est affiché qu’une fois quand vous créez l’endpoint et commence par whsec_. Stockez-le en sécurité ; c’est la seule chose qui prouve qu’une livraison est authentique.

6Livraison fiable et dédupliquée

La livraison est au moins une fois : Telm s’assure qu’un événement vous parvient, ce qui signifie que le même événement peut occasionnellement arriver deux fois. Comme chaque relivraison réutilise le même id de livraison, vous dédupliquez en stockant les id que vous avez traités et en ignorant les répétitions.

Si votre endpoint est injoignable ou renvoie une erreur, la livraison est réessayée selon un calendrier fixe — environ après une minute, cinq minutes, trente minutes, deux heures et six heures, jusqu’à six tentatives sur environ huit heures et demie. Un endpoint qui continue d’échouer est automatiquement désactivé pour protéger les deux parties, et le propriétaire est prévenu.

• Répondez rapidement avec un statut 2xx ; faites le gros du travail de façon asynchrone après avoir accusé réception.
• Dédupliquez sur l’id de livraison — jamais sur le contenu de la charge utile.
• Un endpoint qui échoue une vingtaine de fois d’affilée sans aucun succès dans une fenêtre de 72 heures est désactivé automatiquement ; réactivez-le une fois votre serveur en bonne santé.

7Gérer les endpoints et lire le journal

Vous enregistrez, modifiez et supprimez les endpoints de webhook via l’API. Quand vous en créez un, vous recevez le secret de signature exactement une fois, choisissez les événements auxquels vous abonner, et le limitez éventuellement à des groupes précis. Un appel de test envoie un ping signé pour que vous puissiez confirmer que votre vérification fonctionne avant que le vrai trafic ne commence.

Chaque endpoint conserve un journal des livraisons que vous pouvez relire pour voir ce qui a été envoyé, quand, et si cela a réussi — pratique pour déboguer un récepteur sans attendre le prochain événement en direct.

• Créez un endpoint et copiez le secret whsec_ immédiatement.
• Envoyez un ping de test pour valider votre vérification de signature de bout en bout.
• Limitez un endpoint à un groupe ou laissez-le ouvert à tous les groupes que vous administrez.
• Lisez le journal des livraisons pour inspecter les tentatives récentes et leurs résultats.

8Bonnes pratiques et erreurs courantes

Un récepteur robuste suit quelques règles qui préviennent les problèmes les plus courants.

• Vérifiez la signature sur les octets bruts du corps — analyser d’abord en JSON puis re-sérialiser peut changer les octets et casser la vérification.
• Renvoyez un 2xx rapidement et traitez plus tard ; un gestionnaire lent provoque des délais d’attente et des réessais inutiles.
• Rendez le traitement idempotent pour qu’un événement relivré ne compte pas deux fois.
• Utilisez HTTPS sur une URL publiquement joignable ; Telm bloque les adresses internes et privées et ne suit pas les redirections.
• Gardez le secret whsec_ hors des journaux et du code client.