Alertes Discord pour raccourcisseur d'URL : configuration Telegram, payloads, pièges courants

Si un lien court commence à renvoyer 404 à 3h du matin, vous voulez l'alerte dans le même chat où votre astreinte est déjà active. Pour la plupart des équipes d'ingénierie, c'est Discord ; pour les équipes ops et croissance en Europe, c'est souvent Telegram. Elido propose des intégrations Beta pour les deux. Cet article détaille ce que vous collez, le JSON qui arrive de l'autre côté, et les trois modes de défaillance qui piègent les équipes la première semaine.

Deux points d'emblée. Premièrement, les deux connecteurs fonctionnent uniquement par collage de token. Vous générez une URL de webhook ou un token de bot dans l'interface du fournisseur, vous le saisissez dans Elido, et l'intégration est active. Nous ne provisionnons rien automatiquement côté Discord ou Telegram car leurs APIs n'exposent pas cette capacité. Deuxièmement, chaque alerte est déclenchée par le même bus d'événements qui alimente la fonctionnalité webhooks, les contrats de payload sont donc stables et documentés.

Pourquoi ces deux-là sont en Beta et pas en Live

Le catalogue d'intégrations d'Elido marque les intégrations comme Live quand nous pouvons faire trois choses pour vous en un clic : enregistrer la ressource fournisseur, attacher les bons scopes, et la supprimer à la déconnexion. Notion, Linear et Pipedrive remplissent les critères car ils exposent OAuth ainsi qu'une API de ressources.

Les webhooks Discord et les bots Telegram, non. L'API Webhooks de Discord nécessite un utilisateur bot avec la permission Gérer les webhooks sur un salon spécifique ; pas de flux de consentement que nous puissions piloter. Telegram est plus contraignant encore : BotFather est une interface conversationnelle sans émission de tokens exploitable par une machine. Nous vous demandons donc d'effectuer 90 secondes de configuration côté fournisseur, puis nous prenons en charge tout le reste. Le token est conservé dans notre stockage avec chiffrement d'enveloppe et ne quitte jamais le dispatcher webhook d'api-core.

Le badge Beta signifie : "ça fonctionne, les payloads sont stables, mais l'UX de connexion/déconnexion requiert une étape supplémentaire." Si vous avez besoin d'un auto-provisionnement aujourd'hui, Slack est en Live et tourne sur le même pipeline de transformateurs.

Guide de configuration : Discord en premier

Dans Discord, ouvrez le salon cible, cliquez sur l'icône engrenage et choisissez Intégrations -> Webhooks -> Nouveau Webhook. Donnez-lui un nom comme elido-alerts, téléchargez éventuellement l'avatar Elido depuis /blog/covers, et copiez l'URL du webhook. Elle ressemble à ceci :

https://discord.com/api/webhooks/123456789012345678/AbCdEf-tokenstring

Cette URL est le secret. Quiconque la possède peut publier dans votre salon. Traitez-la comme un mot de passe.

De retour dans Elido, allez dans Paramètres de l'espace de travail -> Intégrations -> Discord. Collez l'URL, choisissez les types d'événements dans la sélection multiple (broken_link, click_threshold, scan_failure, redirect_chain_change, qr_scan_anomaly) et enregistrez. Le formulaire exécute d'abord un événement de test synthétique ; si Discord renvoie autre chose que 204, l'enregistrement échoue et nous affichons l'erreur en ligne.

Telegram se fait en deux étapes. Ouvrez un chat avec BotFather, exécutez /newbot, nommez-le et copiez le token. Il ressemble à 7891234567:AAH-tokenstring. Ajoutez ensuite le bot au chat où vous souhaitez recevoir les alertes (chat privé, groupe ou salon) et envoyez n'importe quel message. Dans Elido, collez le token, cliquez sur "Trouver les chats", choisissez dans la liste des chats visibles par le bot, et enregistrez.

L'étape "Trouver les chats" appelle une fois getUpdates de Telegram pour lister les chat IDs que votre bot a vus. Si la liste est vide, le bot a bien été ajouté mais n'a reçu aucun message - envoyez-en un et réessayez.

La structure réelle du payload

C'est là que la plupart des tutoriels "alertes dans le chat" deviennent vagues. Voici ce qui arrive réellement.

Pour Discord, nous envoyons un seul embed par événement, et non la chaîne content héritée. Le transformateur dans services/api-core/internal/webhooks/delivery/transformers.go construit cette structure :

{
  "username": "Elido",
  "embeds": [
    {
      "title": "Broken link detected",
      "description": "https://elido.me/launch -> 404 Not Found",
      "color": 15548997,
      "timestamp": "2026-06-04T09:14:22.000Z",
      "fields": [
        { "name": "Slug", "value": "launch", "inline": true },
        { "name": "Workspace", "value": "acme-prod", "inline": true },
        { "name": "Status", "value": "404", "inline": true },
        { "name": "First seen", "value": "2026-06-04 09:13:11 UTC" },
        { "name": "Last 5 redirects", "value": "blocked since 09:13:11" }
      ],
      "footer": { "text": "Elido alerts - broken_link" },
      "url": "https://elido.app/links/launch"
    }
  ]
}

L'entier color est la valeur décimale du code hexadécimal. Nous utilisons quatre niveaux de sévérité : info 3447003 (bleu), success 2280516 (vert), warn 15844367 (ambre), error 15548997 (rouge). Plus de détails sur ce mapping dans un instant.

Telegram fonctionne différemment. Nous utilisons parse_mode: "HTML" car Markdown V2 nécessite d'échapper une douzaine de caractères et devient vite illisible. L'appel sendMessage ressemble à ceci :

{
  "chat_id": -1001234567890,
  "parse_mode": "HTML",
  "disable_web_page_preview": true,
  "text": "<b>Broken link detected</b>\n<code>elido.me/launch</code> -> 404\n\nSlug: <code>launch</code>\nWorkspace: <code>acme-prod</code>\nFirst seen: 2026-06-04 09:13:11 UTC\n\n<a href=\"https://elido.app/links/launch\">Open in Elido</a>"
}

Nous mettons disable_web_page_preview à true pour éviter que le chat ne gonfle lorsque l'URL de l'alerte déclencherait autrement un aperçu. Les prévisualisations de liens en ligne sont parasites dans un fil d'astreinte.

Les deux transports sont relancés avec le même backoff : 1s, 5s, 30s, 5min, 30min. Après cinq échecs, l'intégration est mise en pause automatiquement et un email est envoyé. Nous journalisons chaque tentative dans ClickHouse, interrogeable via le guide d'observabilité.

Correspondance sévérité - couleur

La couleur est le seul signal que les utilisateurs Discord perçoivent d'un coup d'oeil. Nous avons retenu quatre niveaux de sévérité, cohérents sur toutes les intégrations supportant la couleur :

• info (#3B82F6, bleu) - nouveau lien créé via API, premier scan d'une destination, page bio publiée. Pas d'action requise, simple information.
• success (#22C55E, vert) - vérificateur de liens rétabli, certificat renouvelé pour un domaine personnalisé, seuil de conversion atteint.
• warn (#F59E0B, ambre) - le taux de clics est 3x la référence sur 7 jours, la chaîne de redirection est passée de 2 à 4 sauts, la vélocité de scan QR a chuté de 80%. Mérite un regard humain.
• error (#EF4444, rouge) - broken_link, scan_failure (Google Safe Browsing a signalé votre destination), TLS de domaine personnalisé expiré, le dispatcher webhook a abandonné après 5 tentatives.

Telegram ne rend pas les couleurs, nous préfixons donc le message avec un emoji correspondant : diamant bleu, coche verte, avertissement jaune, croix rouge. Même sémantique, transport différent. Pour filtrer les alertes Telegram dans votre client aux seuls événements rouges, cherchez l'emoji croix dans le texte.

Modes de défaillance courants (et comment les repérer)

Trois problèmes surviennent en production. Ils sont faciles à corriger une fois que l'on sait quoi chercher.

Rate limit Discord sur un webhook bavard. Discord plafonne chaque URL de webhook à 50 requêtes par seconde et environ 30/minute en régime soutenu. Reliez un webhook à chaque click_threshold d'une campagne virale et vous l'atteindrez. Symptômes : les alertes arrivent en lots avec un délai de 30 à 60 secondes, réponses 429 dans le journal d'intégration. Solution : activez le throttle par événement (désactivé par défaut) pour regrouper les événements déclenchés dans une fenêtre de 10 secondes en un seul embed.

Mode confidentialité du bot Telegram. Le mode confidentialité est activé par défaut pour les nouveaux bots et n'affecte que les messages que le bot peut lire dans les groupes. Les appels sortants sendMessage ne sont pas concernés. Le vrai piège : lorsque vous ajoutez le bot à un groupe, Telegram exige que le bot reçoive au moins un message avant que getUpdates remonte ce chat_id. Si "Trouver les chats" renvoie une liste vide, envoyez n'importe quel message au bot et réessayez. Pour les salons (pas les groupes), ajoutez le bot en tant qu'administrateur avec les droits de publication, sans la contrainte du message initial.

Rotation de token. Les deux transports stockent le secret chiffré via la couche de chiffrement d'enveloppe de l'ADR-0036. Le texte en clair ne réside jamais dans Postgres ni dans les journaux. Lorsqu'un token fuite (capture d'écran dans Slack, entrée dans le journal d'audit Discord qui ne devrait pas exister), la rotation se fait en deux clics : révoquer chez le fournisseur, coller la nouvelle valeur dans Elido. La ligne d'intégration, les filtres d'événements et l'historique ClickHouse restent intacts car ils sont indexés sur l'UUID de l'intégration, pas sur le secret.

Quand choisir lequel

Si votre équipe vit dans Discord, utilisez Discord. Le format embed est plus riche, les champs en ligne s'affichent de manière prévisible sur bureau et mobile, et vous bénéficiez des niveaux de couleur gratuitement.

Si votre équipe est sur Telegram (courant pour les équipes ops européennes, les équipes de développeurs d'Europe de l'Est, et les produits liés aux cryptos), utilisez Telegram. L'API getUpdates et sendMessage est d'une simplicité absolue, et le mode HTML couvre 95% des besoins de formatage.

Si vous avez besoin des deux, utilisez les deux. Chaque intégration est une ligne distincte avec son propre filtre d'événements, vous pouvez donc router les événements de sévérité error vers Discord et les avertissements vers un groupe Telegram "bruit de fond". Certains de nos clients font exactement cela.

Pour tout ce qui est en dehors du chat - mises à jour CRM, automatisation marketing, pipelines BI - Zapier et l'API webhooks sont les bons outils. Le chat est pour les humains qui réagissent aux événements. Les webhooks sont pour les systèmes qui réagissent aux événements.

Ce pour quoi vous ne devriez pas les utiliser

N'utilisez pas Discord ou Telegram comme seul moniteur de link-rot. Le chat est éphémère. Si l'alerte défile pendant un lancement chargé, vous ne la retrouverez pas. Utilisez le chat comme couche de signal élevé au-dessus d'un vrai stack d'observabilité : le vérificateur de liens d'Elido pour les vérifications synthétiques, Datadog ou Sentry pour les traces, et le chat pour les événements qu'un humain doit réellement voir.

Ne mettez pas de données personnelles dans les payloads d'alertes. Le payload par défaut contient le slug du lien et l'ID de l'espace de travail, jamais l'IP du clic ni l'identifiant du visiteur. Si vous attachez des métadonnées personnalisées via l'API et que ces métadonnées contiennent des données personnelles, elles se retrouveront dans l'historique de chat Discord ou Telegram. Aucun des deux fournisseurs ne figure sur la liste DPA de la plupart des entreprises. Cantonnez-vous aux données opérationnelles.

Ce qui est sur la roadmap

L'auto-provisionnement pour Discord est possible si nous nous déployons en tant que bot Discord plutôt que consommateur de webhook. Nous l'avons prototypé. La clé est de permettre aux utilisateurs d'accorder au bot Elido l'accès à un salon via un flux de consentement de type OAuth, après quoi nous créons le webhook côté serveur. Ce n'est pas prévu pour le prochain trimestre, mais cela passerait Discord en Live.

Telegram n'a pas de voie propre. BotFather est une interface réservée aux humains, l'auto-provisionnement complet est donc exclu. Les mises à jour de la roadmap se trouvent dans le changelog.

Vous avez besoin d'une plateforme de chat que nous ne supportons pas encore (Mattermost ? Microsoft Teams via Power Automate ?), contactez l'équipe à /about. Les plans et les limites de sièges sont sur la page de tarifs ; Discord et Telegram sont disponibles à partir du plan Pro.