ElSigm Documentation
Interactions Endpoint URL

Point de terminaison des interactions

Documentation technique complète du point de terminaison HTTP des interactions Discord appliqué à ElSigm : architecture, vérification de signature Ed25519, protocole de validation, typologie complète des interactions et des réponses, contraintes de latence, gestion des erreurs, implémentations de référence et procédure de mise en service.

Champ : Interactions Endpoint URL Application : 1361056395524313158 Signature : Ed25519 Fenêtre : 3 secondes Mode actuel : Passerelle WebSocket

État actuel : ElSigm fonctionne en mode passerelle

À lire avant toute configuration

ElSigm reçoit aujourd'hui ses interactions par la passerelle WebSocket de Discord, au moyen d'une connexion permanente sortante établie par la bibliothèque discord.py. Dans cette architecture, le champ Interactions Endpoint URL du portail développeur doit rester vide. Y inscrire une adresse alors qu'aucun serveur HTTP n'écoute derrière entraînerait l'échec de la validation par Discord et, en cas de validation forcée, la rupture complète du traitement des commandes.

Cette page conserve néanmoins toute son utilité. Elle documente le mécanisme dans son intégralité, pour trois raisons.

D'abord parce qu'elle constitue la documentation de référence à laquelle renvoyer si le champ venait à être renseigné un jour, notamment lors d'une migration vers une architecture sans état.

Ensuite parce qu'elle permet de répondre aux questions légitimes que se posent les administrateurs et les auditeurs sur la manière dont le bot reçoit et traite les commandes.

Enfin parce que le modèle HTTP présente des avantages réels pour certaines évolutions envisageables : exécution sans processus permanent, montée en charge horizontale, hébergement sur des plateformes de fonctions serverless.

Comparaison des deux modèles

CritèrePasserelle WebSocket actuelPoint de terminaison HTTP
Sens de la connexionSortante, du bot vers DiscordEntrante, de Discord vers le bot
Adresse publique requiseNonOui, avec certificat TLS valide
Processus permanentRequisNon requis
Événements reçusTous : messages, membres, réactions, présencesInteractions uniquement
Réseau InterPub possibleOuiNon — les messages ne sont pas transmis
Tâches de fond périodiquesOuiNécessitent un ordonnanceur externe
Vérification de signatureNon applicableObligatoire, Ed25519
Sensibilité aux attaques réseauFaible, aucun port exposéRéelle, surface exposée à Internet
Coût d'hébergement au reposContinuNul en l'absence de trafic
Montée en chargePar fragmentationHorizontale naturelle

Incompatibilité structurelle avec le réseau InterPub

Le cœur fonctionnel d'ElSigm repose sur la lecture des messages publiés dans les salons InterPub. Or le point de terminaison HTTP ne reçoit que les interactions : commandes en barre oblique, clics sur boutons, soumissions de formulaires, sélections de menus. Il ne reçoit jamais les événements de message, d'arrivée de membre ou de réaction. Une migration complète vers le modèle HTTP supprimerait donc purement et simplement le réseau InterPub, le mode absent, la détection des mentions et l'ensemble des tâches périodiques. Une architecture hybride — passerelle pour les événements, HTTP pour les interactions — est techniquement possible mais notablement plus complexe à opérer.

Définition et rôle du point de terminaison

Le point de terminaison des interactions désigne une adresse HTTPS publique que vous déclarez auprès de Discord et vers laquelle la plateforme envoie une requête POST chaque fois qu'un utilisateur interagit avec votre application.

Dans ce modèle, votre application n'a pas besoin de maintenir une connexion permanente. Elle se comporte comme un serveur web ordinaire : elle attend, reçoit une requête, la vérifie, la traite et répond.

Ce que le point de terminaison reçoit

  • Les commandes en barre oblique — /help, /ping, /profil, /config_interpub et l'ensemble des commandes de l'application.
  • Les commandes contextuelles déclenchées depuis le menu d'un message ou d'un utilisateur.
  • Les clics sur composants — boutons d'acceptation ou de refus d'une annonce, boutons de signalement, bouton de participation à un tirage au sort, boutons de pagination.
  • Les sélections dans un menu déroulant.
  • Les soumissions de formulaires modaux — configuration d'une annonce Premium, rédaction d'une suggestion, saisie d'un identifiant dans le panneau de vérification.
  • Les requêtes d'autocomplétion émises pendant la frappe d'un paramètre de commande.
  • Les requêtes de validation de type PING, décrites plus bas.

Ce que le point de terminaison ne reçoit jamais

  • Les messages publiés dans un salon.
  • Les arrivées, départs et mises à jour de membres.
  • Les ajouts et retraits de réactions.
  • Les changements de présence ou de statut.
  • Les créations, modifications et suppressions de salons ou de rôles.
  • Les événements vocaux.

Formulation simple

La passerelle est un flux permanent qui vous apporte tout ce qui se passe. Le point de terminaison est une boîte aux lettres qui reçoit uniquement ce qu'un utilisateur déclenche volontairement en interagissant avec votre application.

Prérequis techniques

Un point de terminaison ne peut être validé par Discord que si l'ensemble des conditions suivantes est réuni.

ExigenceDétailConséquence en cas de manquement
Protocole HTTPSLe protocole HTTP simple est refusé, sans exceptionValidation impossible
Certificat TLS valideÉmis par une autorité reconnue, non expiré, chaîne complèteValidation impossible
Accessibilité publiqueAucun pare-feu, aucun réseau privé, aucune authentification préalableDiscord ne peut pas joindre l'adresse
Méthode POST acceptéeLa route doit accepter POST avec un corps JSONErreur 405 lors de la validation
Absence de redirectionAucun code 301, 302, 307 ou 308 sur la routeDiscord ne suit pas les redirections
Vérification de signatureContrôle Ed25519 obligatoire sur chaque requêteValidation refusée par Discord
Rejet des signatures invalidesRéponse 401 obligatoire, jamais 200 ni 400Validation refusée par Discord
Réponse au PINGCorps {"type": 1} avec un code 200Validation refusée
Latence de réponseTrois secondes au maximumInteraction perdue, message d'échec côté utilisateur
Accès au corps brutLe corps doit être lisible avant toute désérialisationSignature systématiquement invalide
StabilitéLe point de terminaison doit rester joignable en permanenceDiscord peut désactiver l'application après échecs répétés

Le piège du corps désérialisé

La signature Ed25519 porte sur les octets exacts du corps de la requête. De nombreux cadriciels web désérialisent automatiquement le JSON avant que votre code n'y accède ; si vous re-sérialisez ensuite l'objet pour vérifier la signature, l'ordre des clés, les espaces et l'échappement des caractères diffèrent, et la vérification échoue systématiquement. Vous devez impérativement conserver le corps brut. C'est de très loin l'erreur la plus fréquente lors de la mise en place d'un point de terminaison.

Vérification de la signature Ed25519

Chaque requête envoyée par Discord est signée cryptographiquement. Cette signature permet de garantir que la requête provient bien de Discord et n'a pas été altérée en transit. Sa vérification est obligatoire et constitue le seul rempart contre l'envoi de fausses interactions par un tiers.

En-têtes transmis

En-têteContenuUsage
X-Signature-Ed25519Signature hexadécimale de 128 caractèresSignature à vérifier
X-Signature-TimestampHorodatage Unix en secondesPréfixe du message signé, protection anti-rejeu
Content-Typeapplication/jsonFormat du corps
User-AgentChaîne identifiant DiscordInformation, ne doit pas servir de contrôle d'accès

Message signé

Le message effectivement signé est la concaténation, dans cet ordre exact et sans séparateur, de l'horodatage puis du corps brut de la requête :

message_signe = X-Signature-Timestamp + corps_brut

La vérification s'effectue au moyen de la clé publique de l'application, disponible dans l'onglet General Information du portail développeur sous l'intitulé Public Key. Cette clé est publique par nature : sa divulgation ne présente aucun risque, contrairement au jeton du bot et au secret d'application.

Comportement attendu en cas d'échec

Toute requête dont la signature est invalide, absente ou malformée doit recevoir une réponse 401 Unauthorized. Discord teste explicitement ce comportement lors de la validation en envoyant délibérément des requêtes mal signées. Répondre 200, 400 ou 403 fait échouer la validation.

Implémentation en Python avec PyNaCl

from nacl.signing import VerifyKey
from nacl.exceptions import BadSignatureError

PUBLIC_KEY = "VOTRE_CLE_PUBLIQUE_HEXADECIMALE"   # portail → General Information
_verify_key = VerifyKey(bytes.fromhex(PUBLIC_KEY))

def signature_valide(signature: str, timestamp: str, corps_brut: bytes) -> bool:
    """Vérifie la signature Ed25519 d'une requête Discord."""
    if not signature or not timestamp:
        return False
    try:
        _verify_key.verify(
            timestamp.encode() + corps_brut,
            bytes.fromhex(signature),
        )
        return True
    except (BadSignatureError, ValueError):
        return False

Implémentation en JavaScript avec tweetnacl

import nacl from 'tweetnacl';

const PUBLIC_KEY = process.env.DISCORD_PUBLIC_KEY;

export function signatureValide(signature, timestamp, corpsBrut) {
  if (!signature || !timestamp) return false;
  try {
    return nacl.sign.detached.verify(
      Buffer.concat([Buffer.from(timestamp, 'utf8'), corpsBrut]),
      Buffer.from(signature, 'hex'),
      Buffer.from(PUBLIC_KEY, 'hex'),
    );
  } catch {
    return false;
  }
}

Protection contre le rejeu

L'horodatage permet de rejeter les requêtes trop anciennes. Une fenêtre de tolérance de cinq minutes est un choix raisonnable : elle absorbe les dérives d'horloge légitimes tout en limitant la fenêtre d'exploitation d'une requête interceptée.

import time

FENETRE_TOLERANCE = 300   # cinq minutes

def horodatage_acceptable(timestamp: str) -> bool:
    try:
        return abs(time.time() - int(timestamp)) <= FENETRE_TOLERANCE
    except (TypeError, ValueError):
        return False

Comparaison en temps constant

Les bibliothèques Ed25519 sérieuses effectuent leurs comparaisons en temps constant. N'écrivez jamais votre propre comparaison de signatures avec un opérateur d'égalité classique : le temps d'exécution variable révélerait de l'information exploitable par une attaque temporelle.

Protocole de validation : PING et PONG

Lorsque vous enregistrez une adresse dans le champ Interactions Endpoint URL, Discord procède immédiatement à une séquence de validation. Cette séquence doit réussir intégralement, faute de quoi l'enregistrement est refusé.

Séquence exécutée par Discord

  1. Requête PING correctement signée

    Discord envoie une requête POST dont le corps est {"type": 1}, accompagnée d'une signature valide. Votre serveur doit répondre 200 avec le corps {"type": 1}.

  2. Requête à signature invalide

    Discord envoie une requête délibérément mal signée. Votre serveur doit répondre 401. Toute autre réponse fait échouer la validation.

  3. Requête à en-têtes manquants

    Discord peut omettre les en-têtes de signature. Votre serveur doit également répondre 401.

  4. Contrôle du délai

    Les réponses doivent parvenir dans le délai imparti. Un serveur trop lent échoue à la validation.

Échange nominal

--- Requête entrante ---
POST /api/interactions HTTP/1.1
Host: votre-domaine.tld
Content-Type: application/json
X-Signature-Ed25519: 4f8e2a...c91d
X-Signature-Timestamp: 1786377600

{"type": 1}

--- Réponse attendue ---
HTTP/1.1 200 OK
Content-Type: application/json

{"type": 1}

Échange en cas de signature invalide

--- Requête entrante ---
POST /api/interactions HTTP/1.1
X-Signature-Ed25519: 0000000000000000...0000
X-Signature-Timestamp: 1786377600

{"type": 1}

--- Réponse attendue ---
HTTP/1.1 401 Unauthorized
Content-Type: text/plain

invalid request signature

Revalidation périodique

Discord revérifie périodiquement la disponibilité du point de terminaison. En cas d'indisponibilité prolongée ou d'échecs répétés, la plateforme peut désactiver l'adresse enregistrée, ce qui interrompt le traitement de toutes les interactions jusqu'à correction et réenregistrement manuel.

Typologie des interactions reçues

Le champ type du corps de la requête indique la nature de l'interaction.

ValeurNomDéclencheurRéponse attendue
1PINGValidation par DiscordType 1 (PONG)
2APPLICATION_COMMANDCommande en barre oblique ou contextuelleType 4 ou 5
3MESSAGE_COMPONENTClic sur bouton ou sélection dans un menuType 4, 5, 6, 7 ou 9
4APPLICATION_COMMAND_AUTOCOMPLETEFrappe dans un paramètre à autocomplétionType 8
5MODAL_SUBMITEnvoi d'un formulaire modalType 4, 5, 6 ou 7

Structure d'une interaction de commande

{
  "id": "1398075278592311417",
  "application_id": "1361056395524313158",
  "type": 2,
  "token": "jeton_opaque_valable_15_minutes",
  "version": 1,
  "guild_id": "1361756362933010586",
  "channel_id": "1363113136965812426",
  "member": {
    "user": {
      "id": "781287178743447552",
      "username": "exemple",
      "global_name": "Exemple",
      "avatar": "a1b2c3d4e5f6"
    },
    "roles": ["967844785983479848"],
    "permissions": "2147483647",
    "joined_at": "2026-01-15T10:00:00.000000+00:00"
  },
  "data": {
    "id": "1398075278592311418",
    "name": "profil",
    "type": 1,
    "options": [
      { "name": "membre", "type": 6, "value": "781287178743447552" }
    ]
  },
  "locale": "fr",
  "guild_locale": "fr"
}

Structure d'une interaction de composant

{
  "type": 3,
  "id": "…",
  "token": "…",
  "data": {
    "custom_id": "gw_join",
    "component_type": 2
  },
  "message": { "id": "…", "content": "…" },
  "member": { "user": { "id": "781287178743447552" } }
}

Le champ custom_id est l'identifiant que votre application a attribué au composant lors de sa création. Dans ElSigm, ces identifiants suivent des conventions explicites : gw_join pour la participation à un tirage au sort, rp_report pour le signalement d'une annonce, rp_sb pour le signalement d'un selfbot, sb_yes et sb_no pour la qualification d'un selfbot, deban_btn pour le déblocage d'un utilisateur, confirm_<identifiant> pour l'accusé de réception du message de bienvenue.

Structure d'une soumission de formulaire

{
  "type": 5,
  "data": {
    "custom_id": "config_pub_modal",
    "components": [
      {
        "type": 1,
        "components": [
          { "type": 4, "custom_id": "title_inp", "value": "Rejoignez-nous" }
        ]
      },
      {
        "type": 1,
        "components": [
          { "type": 4, "custom_id": "desc_inp", "value": "Description de l'annonce…" }
        ]
      }
    ]
  }
}

Typologie des réponses possibles

La réponse à une interaction est un objet JSON comportant obligatoirement un champ type et, selon les cas, un champ data.

TypeNomEffetCas d'usage dans ElSigm
1PONGRéponse au PING de validationValidation du point de terminaison
4CHANNEL_MESSAGE_WITH_SOURCEEnvoie un message immédiat/help, /stats, /profil
5DEFERRED_CHANNEL_MESSAGE_WITH_SOURCEAffiche « réfléchit… », réponse ultérieure/meme, qui interroge une interface externe
6DEFERRED_UPDATE_MESSAGEAccuse réception sans modification visibleProgression dans le jeu Simon
7UPDATE_MESSAGEModifie le message portant le composantPagination du panneau de vérification
8APPLICATION_COMMAND_AUTOCOMPLETE_RESULTRenvoie des suggestions de saisieNon utilisé actuellement
9MODALOuvre un formulaire modal/config_pub, /suggestion, saisie d'identifiant
10PREMIUM_REQUIREDInvite à souscrire une offre payanteNon utilisé, le bot étant gratuit
12LAUNCH_ACTIVITYLance une activité intégréeNon utilisé

Réponse immédiate simple

{
  "type": 4,
  "data": {
    "content": "🏓 Pong ! Latence : 42 ms",
    "flags": 64
  }
}

L'indicateur 64 correspond au caractère éphémère : le message n'est visible que par la personne ayant déclenché l'interaction. ElSigm l'utilise systématiquement pour les réponses contenant des données personnelles — notes, avertissements, configuration Premium, panneau de vérification.

Réponse enrichie avec composants

{
  "type": 4,
  "data": {
    "embeds": [{
      "title": "📘 Commandes disponibles",
      "description": "Liste des commandes d'ElSigm.",
      "color": 3447003,
      "fields": [
        { "name": "🔧 Configuration", "value": "`/config_interpub`\n`/config_pub`", "inline": false }
      ],
      "footer": { "text": "ElSigm • Interpublicité intelligente" }
    }],
    "components": [{
      "type": 1,
      "components": [
        { "type": 2, "style": 5, "label": "💬 Support", "url": "https://discord.gg/aCszSWa8zd" },
        { "type": 2, "style": 1, "label": "🎉 Participer", "custom_id": "gw_join" }
      ]
    }],
    "flags": 64
  }
}

Ouverture d'un formulaire modal

{
  "type": 9,
  "data": {
    "custom_id": "config_pub_modal",
    "title": "Configurer votre publicité Premium",
    "components": [
      {
        "type": 1,
        "components": [{
          "type": 4,
          "custom_id": "title_inp",
          "label": "Titre",
          "style": 1,
          "max_length": 60,
          "required": true
        }]
      },
      {
        "type": 1,
        "components": [{
          "type": 4,
          "custom_id": "desc_inp",
          "label": "Description",
          "style": 2,
          "max_length": 850,
          "required": true
        }]
      }
    ]
  }
}

Un formulaire modal ne peut pas suivre une réponse différée

L'ouverture d'un formulaire modal, de type 9, doit constituer la toute première réponse à une interaction. Il est impossible de différer d'abord puis d'ouvrir un formulaire ensuite : le formulaire ne s'affichera jamais. Si votre traitement requiert une vérification préalable lente, restructurez le flux — par exemple en ouvrant immédiatement le formulaire et en effectuant la vérification à sa soumission.

Contrainte de latence et réponses différées

Discord impose une fenêtre de trois secondes pour la réponse initiale à une interaction. Ce délai court à partir de l'émission de la requête, et non de sa réception : la latence réseau, la résolution DNS et la négociation TLS sont incluses.

Ce qui se produit en cas de dépassement

L'utilisateur voit le message « L'application n'a pas répondu ». Le jeton d'interaction devient inutilisable, et aucun rattrapage ultérieur n'est possible. L'interaction est définitivement perdue.

Stratégie de réponse différée

Lorsqu'un traitement risque de dépasser trois secondes — appel à une interface externe, lecture volumineuse, opération en boucle sur de nombreux serveurs — il faut répondre immédiatement avec un type 5 puis compléter la réponse ensuite.

# 1) accusé de réception immédiat, sous les trois secondes
{ "type": 5 }

# 2) traitement effectif, jusqu'à quinze minutes disponibles
#    puis envoi du résultat via l'API :
PATCH https://discord.com/api/v10/webhooks/{application_id}/{token}/messages/@original
Content-Type: application/json

{ "content": "✅ Traitement terminé.", "embeds": [ … ] }

Fenêtres temporelles applicables

OpérationDélaiRemarque
Réponse initiale3 secondesImpératif absolu, sans exception
Validité du jeton d'interaction15 minutesPour les messages complémentaires
Édition de la réponse initiale15 minutesVia la route @original
Messages complémentaires15 minutesNombre non limité dans la fenêtre
Suppression de la réponse initiale15 minutesMéthode DELETE sur @original

Routes complémentaires

POST/webhooks/{application_id}/{token}

Envoie un message complémentaire après la réponse initiale.

GET/webhooks/{application_id}/{token}/messages/@original

Récupère la réponse initiale.

PATCH/webhooks/{application_id}/{token}/messages/@original

Modifie la réponse initiale, notamment après un différé.

DELETE/webhooks/{application_id}/{token}/messages/@original

Supprime la réponse initiale.

Repère pratique appliqué à ElSigm

Dans le code actuel, plusieurs traitements dépasseraient largement la fenêtre de trois secondes en mode HTTP : la commande /meme interroge successivement jusqu'à trois espaces communautaires Reddit ; la commande /ping comporte une animation de plus de deux secondes ; la diffusion d'une annonce parcourt l'ensemble des serveurs du réseau avec une pause entre chaque envoi. Toutes exigeraient une réponse différée.

Implémentations de référence

Python — aiohttp

import os, json, time
from aiohttp import web
from nacl.signing import VerifyKey
from nacl.exceptions import BadSignatureError

PUBLIC_KEY = os.environ["DISCORD_PUBLIC_KEY"]
VERIFY_KEY = VerifyKey(bytes.fromhex(PUBLIC_KEY))
FENETRE    = 300

def verifier(signature, timestamp, corps: bytes) -> bool:
    if not signature or not timestamp:
        return False
    try:
        if abs(time.time() - int(timestamp)) > FENETRE:
            return False
        VERIFY_KEY.verify(timestamp.encode() + corps, bytes.fromhex(signature))
        return True
    except (BadSignatureError, ValueError, TypeError):
        return False

async def interactions(request: web.Request):
    corps     = await request.read()                       # corps BRUT, indispensable
    signature = request.headers.get("X-Signature-Ed25519")
    timestamp = request.headers.get("X-Signature-Timestamp")

    if not verifier(signature, timestamp, corps):
        return web.Response(status=401, text="invalid request signature")

    data  = json.loads(corps)
    itype = data.get("type")

    # ── PING de validation
    if itype == 1:
        return web.json_response({"type": 1})

    # ── Commande en barre oblique
    if itype == 2:
        nom = data["data"]["name"]
        if nom == "ping":
            return web.json_response({
                "type": 4,
                "data": {"content": "🏓 Pong !", "flags": 64},
            })
        if nom == "help":
            return web.json_response({"type": 4, "data": embed_aide()})
        if nom == "meme":
            request.app.loop.create_task(traiter_meme(data))   # traitement long
            return web.json_response({"type": 5})              # différé
        return web.json_response({
            "type": 4,
            "data": {"content": "❓ Commande inconnue.", "flags": 64},
        })

    # ── Clic sur un composant
    if itype == 3:
        cid = data["data"]["custom_id"]
        if cid == "gw_join":
            return web.json_response({
                "type": 4,
                "data": {"content": "✅ Participation enregistrée !", "flags": 64},
            })
        if cid.startswith("rp_"):
            return web.json_response({
                "type": 4,
                "data": {"content": "✅ Signalement transmis.", "flags": 64},
            })
        return web.json_response({"type": 6})   # accusé silencieux

    # ── Soumission d'un formulaire modal
    if itype == 5:
        champs = extraire_champs(data["data"]["components"])
        enregistrer_config_premium(data["member"]["user"]["id"], champs)
        return web.json_response({
            "type": 4,
            "data": {"content": "✅ Configuration enregistrée.", "flags": 64},
        })

    return web.Response(status=400, text="type non pris en charge")

def extraire_champs(rows) -> dict:
    """Aplatit la structure imbriquée d'un formulaire modal."""
    return {
        c["custom_id"]: c.get("value", "")
        for row in rows for c in row.get("components", [])
    }

app = web.Application()
app.add_routes([web.post("/api/interactions", interactions)])

if __name__ == "__main__":
    web.run_app(app, port=int(os.environ.get("PORT", 8080)))

Python — FastAPI

import os, json
from fastapi import FastAPI, Request, Response
from nacl.signing import VerifyKey
from nacl.exceptions import BadSignatureError

app        = FastAPI()
VERIFY_KEY = VerifyKey(bytes.fromhex(os.environ["DISCORD_PUBLIC_KEY"]))

@app.post("/api/interactions")
async def interactions(request: Request):
    corps = await request.body()                # corps BRUT avant désérialisation
    sig   = request.headers.get("x-signature-ed25519", "")
    ts    = request.headers.get("x-signature-timestamp", "")
    try:
        VERIFY_KEY.verify(ts.encode() + corps, bytes.fromhex(sig))
    except (BadSignatureError, ValueError):
        return Response(status_code=401, content="invalid request signature")

    data = json.loads(corps)
    if data["type"] == 1:
        return {"type": 1}
    return {"type": 4, "data": {"content": "Reçu.", "flags": 64}}

Spécificité FastAPI

N'utilisez pas un modèle Pydantic comme paramètre de la route : le corps serait consommé et désérialisé avant que vous n'y accédiez, et await request.body() renverrait alors un contenu vide ou réordonné. Lisez toujours le corps brut en premier, puis désérialisez-le vous-même.

Node.js — Express

import express from 'express';
import nacl from 'tweetnacl';

const app = express();
const PUBLIC_KEY = process.env.DISCORD_PUBLIC_KEY;

// conservation du corps brut pour la vérification
app.use(express.json({
  verify: (req, _res, buf) => { req.rawBody = buf; },
}));

app.post('/api/interactions', (req, res) => {
  const signature = req.get('X-Signature-Ed25519');
  const timestamp = req.get('X-Signature-Timestamp');
  if (!signature || !timestamp) return res.status(401).send('missing headers');

  let valide = false;
  try {
    valide = nacl.sign.detached.verify(
      Buffer.concat([Buffer.from(timestamp, 'utf8'), req.rawBody]),
      Buffer.from(signature, 'hex'),
      Buffer.from(PUBLIC_KEY, 'hex'),
    );
  } catch { valide = false; }
  if (!valide) return res.status(401).send('invalid request signature');

  const interaction = req.body;

  if (interaction.type === 1) return res.json({ type: 1 });

  if (interaction.type === 2) {
    return res.json({
      type: 4,
      data: { content: `Commande ${interaction.data.name} reçue.`, flags: 64 },
    });
  }

  if (interaction.type === 3) return res.json({ type: 6 });

  return res.status(400).send('unsupported type');
});

app.listen(process.env.PORT || 8080);

Node.js — bibliothèque officielle discord-interactions

import express from 'express';
import { verifyKeyMiddleware, InteractionType, InteractionResponseType } from 'discord-interactions';

const app = express();

app.post(
  '/api/interactions',
  verifyKeyMiddleware(process.env.DISCORD_PUBLIC_KEY),   // gère signature et 401
  (req, res) => {
    const { type, data } = req.body;
    if (type === InteractionType.PING) {
      return res.send({ type: InteractionResponseType.PONG });
    }
    if (type === InteractionType.APPLICATION_COMMAND) {
      return res.send({
        type: InteractionResponseType.CHANNEL_MESSAGE_WITH_SOURCE,
        data: { content: `Commande ${data.name} exécutée.`, flags: 64 },
      });
    }
    return res.sendStatus(400);
  },
);

app.listen(8080);

Dépendances requises

# Python
pip install pynacl aiohttp          # ou : pip install pynacl fastapi uvicorn

# Node.js
npm install express tweetnacl       # ou : npm install express discord-interactions

Architecture hybride recommandée

Si un point de terminaison HTTP devait être mis en place pour ElSigm sans sacrifier le réseau InterPub, l'architecture suivante serait la plus adaptée.

┌──────────────────────────────────────────────────────────────┐
│                          DISCORD                             │
└───────────────┬──────────────────────────┬───────────────────┘
                │                          │
    WebSocket sortante            HTTPS entrante
    (événements)                  (interactions)
                │                          │
                ▼                          ▼
      ┌──────────────────┐       ┌───────────────────────┐
      │  Processus       │       │  Serveur HTTP         │
      │  passerelle      │       │  /api/interactions    │
      │                  │       │                       │
      │ • on_message     │       │ • signature Ed25519   │
      │ • réseau InterPub│       │ • PING / PONG         │
      │ • AFK, mentions  │       │ • commandes           │
      │ • tâches de fond │       │ • boutons, formulaires│
      └────────┬─────────┘       └───────────┬───────────┘
               │                             │
               └──────────┬──────────────────┘
                          ▼
              ┌───────────────────────┐
              │  Stockage partagé     │
              │  fichiers JSON ou     │
              │  base de données      │
              └───────────────────────┘

Points d'attention de cette architecture

  • Concurrence d'écriture. Deux processus écrivant simultanément dans les mêmes fichiers JSON provoqueraient des pertes de données. Un verrou de fichier, ou mieux, une migration vers une base de données transactionnelle, devient nécessaire.
  • Cohérence des états en mémoire. Le dictionnaire des délais entre annonces et les parties de jeu Simon vivent actuellement en mémoire vive d'un seul processus. Ils devraient être externalisés vers un stockage partagé.
  • Duplication de la logique. Certaines fonctions devraient être accessibles depuis les deux processus, ce qui impose de les extraire dans un module commun.
  • Ordonnancement des tâches périodiques. Les sept boucles de fond actuelles resteraient portées par le processus passerelle.
  • Observabilité. Deux processus impliquent deux flux de journaux à corréler.

Recommandation

Compte tenu de la nature d'ElSigm — dont le cœur est la lecture de messages, incompatible avec le modèle HTTP — le maintien du mode passerelle seul reste le choix le plus sain. Le champ Interactions Endpoint URL doit donc rester vide. Cette page documente l'alternative sans la préconiser.

Sécurité du point de terminaison

Contrôles obligatoires

  • Vérifier la signature avant toute autre opération. Aucune désérialisation, aucun accès à la base, aucune journalisation du contenu avant validation.
  • Répondre 401 sur toute signature invalide, sans détail exploitable dans le corps de la réponse.
  • Rejeter les horodatages hors fenêtre afin de limiter le rejeu.
  • Ne jamais faire confiance au contenu de la requête pour déterminer des droits : les permissions doivent être revérifiées auprès de l'API lorsque l'enjeu est sensible.
  • Valider les identifiants reçus avant de les employer dans une opération de lecture ou d'écriture.

Durcissement de l'infrastructure

  • Limiter la taille maximale du corps accepté, par exemple à 256 kilo-octets, afin d'écarter les envois abusifs.
  • Appliquer une limitation de débit par adresse source en amont de l'application.
  • Placer le service derrière un mandataire inverse assurant la terminaison TLS et le filtrage.
  • Exposer uniquement la route d'interactions ; toute autre route doit renvoyer 404.
  • Ne jamais journaliser le jeton d'interaction, le jeton du bot ni le secret d'application.
  • Charger toutes les valeurs sensibles depuis des variables d'environnement.
  • Maintenir les dépendances cryptographiques à jour.
  • Surveiller le taux de réponses 401 : une hausse soudaine signale une tentative d'envoi de fausses interactions.

Erreurs classiques à éviter

ErreurConséquenceCorrection
Vérifier la signature sur du JSON re-sérialiséÉchec systématiqueConserver et utiliser le corps brut
Répondre 200 à une signature invalideValidation refusée par DiscordRépondre 401
Utiliser le jeton du bot au lieu de la clé publiqueVérification impossibleEmployer la Public Key du portail
Traiter avant de répondreDépassement des trois secondesRépondre en type 5 puis traiter
Placer une redirection sur la routeValidation refuséeServir la route directement
Certificat auto-signéConnexion refusée par DiscordUtiliser une autorité reconnue
Confondre clé publique et secret d'applicationVérification impossibleVérifier l'origine de chaque valeur
Ignorer l'horodatageRejeu possibleContrôler la fenêtre temporelle
Journaliser le corps avant vérificationPollution des journaux par des données non authentifiéesJournaliser après validation
Se fier au champ permissions sans contrôleÉlévation de privilèges possibleRevérifier auprès de l'API

Codes de réponse et diagnostic

Codes que votre serveur doit émettre

CodeSituationCorps
200Interaction traitée avec succèsObjet de réponse JSON
401Signature absente, invalide ou hors fenêtreMessage générique, sans détail
400Corps illisible ou type non pris en chargeMessage générique
405Méthode autre que POSTVide
413Corps excédant la limite fixéeVide
500Erreur interne inattendueMessage générique, détails en journal uniquement

Codes que vous pouvez recevoir de l'API Discord

CodeSignificationRésolution
400Corps de réponse mal forméVérifier la structure JSON et les limites de longueur
401Jeton d'autorisation invalideVérifier l'en-tête Authorization
403Permissions insuffisantesContrôler les permissions du bot sur le salon
404Ressource introuvableJeton expiré, ou message déjà supprimé
429Limite de débit atteinteRespecter l'en-tête Retry-After
500–504Incident côté DiscordRéessayer avec un délai exponentiel

Codes d'erreur applicatifs fréquents

CodeMessageCause
10062Unknown interactionRéponse envoyée après expiration du délai de trois secondes
40060Interaction has already been acknowledgedDeux réponses initiales envoyées pour la même interaction
50001Missing accessLe bot n'a pas accès au salon visé
50013Missing permissionsPermission requise absente
50035Invalid form bodyChamp trop long, couleur invalide, structure incorrecte
30046Maximum number of edits reachedTrop de modifications successives d'un même message

Procédure de mise en service

Si vous décidez de déployer un point de terminaison, suivez cette procédure dans l'ordre indiqué.

  1. Développez et testez localement

    Implémentez la vérification de signature et la réponse au PING. Testez avec un tunnel HTTPS temporaire avant tout déploiement.

  2. Déployez sur une infrastructure joignable

    Assurez-vous que l'adresse répond publiquement en HTTPS avec un certificat valide et sans redirection.

  3. Vérifiez manuellement

    Testez la route avec un appel simulé et contrôlez que les signatures invalides reçoivent bien un 401.

  4. Renseignez le portail développeur

    Dans l'onglet General Information, complétez le champ Interactions Endpoint URL avec l'adresse complète, par exemple https://votre-domaine.tld/api/interactions.

  5. Enregistrez

    Discord exécute immédiatement sa séquence de validation. Une erreur explicite s'affiche en cas d'échec.

  6. Testez de bout en bout

    Exécutez une commande sur un serveur de test et vérifiez que la réponse s'affiche correctement.

  7. Surveillez

    Mettez en place une supervision de la disponibilité et une alerte sur le taux d'erreurs.

Test manuel de la route

# Ce test doit renvoyer 401 : la signature est délibérément invalide
curl -i -X POST https://votre-domaine.tld/api/interactions \
  -H "Content-Type: application/json" \
  -H "X-Signature-Ed25519: 00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000" \
  -H "X-Signature-Timestamp: 1786377600" \
  -d '{"type":1}'

# Attendu : HTTP/1.1 401 Unauthorized

Liste de contrôle avant enregistrement

  • La route répond en HTTPS avec un certificat valide et une chaîne complète.
  • La méthode POST est acceptée avec un corps application/json.
  • Aucune redirection n'est appliquée à la route.
  • Le corps brut est lu avant toute désérialisation.
  • La signature Ed25519 est vérifiée avec la clé publique de l'application.
  • Une signature invalide entraîne une réponse 401.
  • Des en-têtes manquants entraînent une réponse 401.
  • Un PING signé correctement reçoit une réponse 200 avec {"type": 1}.
  • L'horodatage est contrôlé dans une fenêtre raisonnable.
  • Toute réponse est émise en moins de trois secondes.
  • Les traitements longs utilisent une réponse différée de type 5.
  • La clé publique est chargée depuis une variable d'environnement.
  • Aucun secret n'apparaît dans les journaux.
  • Une limitation de débit est en place en amont.
  • La taille maximale du corps est bornée.
  • Une supervision de disponibilité est active.
  • Les commandes ont été enregistrées auprès de Discord.
  • Un serveur de test a permis une validation de bout en bout.

Enregistrement des commandes

Le point de terminaison reçoit les interactions, mais les commandes doivent au préalable être déclarées auprès de Discord. Cette déclaration est indépendante du mode de réception choisi.

Commandes globales

PUT/applications/{application_id}/commands

Remplace l'intégralité des commandes globales. La propagation peut prendre jusqu'à une heure.

Commandes de serveur

PUT/applications/{application_id}/guilds/{guild_id}/commands

Remplace les commandes propres à un serveur. La propagation est immédiate, ce qui en fait le mode privilégié pendant le développement.

Exemple de déclaration

PUT https://discord.com/api/v10/applications/1361056395524313158/commands
Authorization: Bot <TOKEN_DU_BOT>
Content-Type: application/json

[
  { "name": "ping",    "description": "Vérifie la latence du bot",           "type": 1 },
  { "name": "help",    "description": "Afficher la liste des commandes",     "type": 1 },
  { "name": "stats",   "description": "Voir les statistiques du bot",        "type": 1 },
  {
    "name": "profil",
    "description": "Voir votre profil ou celui d'un membre",
    "type": 1,
    "options": [
      { "name": "membre", "description": "Le membre à consulter", "type": 6, "required": false }
    ]
  },
  {
    "name": "config_interpub",
    "description": "Configurer le salon de PUB interpub (admin)",
    "type": 1,
    "default_member_permissions": "8"
  }
]
Type d'optionValeurContenu attendu
SUB_COMMAND1Sous-commande
SUB_COMMAND_GROUP2Groupe de sous-commandes
STRING3Chaîne de caractères
INTEGER4Nombre entier
BOOLEAN5Booléen
USER6Utilisateur ou membre
CHANNEL7Salon
ROLE8Rôle
MENTIONABLE9Utilisateur ou rôle
NUMBER10Nombre décimal
ATTACHMENT11Pièce jointe

Le champ default_member_permissions exprime en décimal le masque de permissions requis. La valeur 8 correspond à la permission Administrateur, appliquée dans ElSigm aux commandes /config_interpub, /avertissement et /giveaway.

Données transitant par le point de terminaison

Cette section documente, en cohérence avec la Politique de Confidentialité, la nature des données présentes dans une requête d'interaction.

ChampNatureUsage par l'applicationConservation
idIdentifiant de l'interactionCorrélation et journalisationNon conservé
tokenJeton opaque de réponseRépondre et compléterMémoire vive uniquement, 15 minutes
member.user.idIdentifiant de l'utilisateurRetrouver ses donnéesSelon la fonction appelée
member.user.usernamePseudonymeAffichageNon conservé
member.user.avatarEmpreinte d'avatarAffichageNon conservé
member.rolesRôles de l'utilisateurContrôle d'accèsNon conservé
member.permissionsMasque de permissionsContrôle d'accèsNon conservé
guild_idIdentifiant du serveurConfiguration InterPubConservé pour la configuration
channel_idIdentifiant du salonConfiguration InterPubConservé pour la configuration
data.optionsParamètres saisisSelon la commandeVariable selon la fonction
data.componentsChamps d'un formulaireConfiguration Premium, suggestionConservé selon la fonction
localeLangue de l'utilisateurLocalisation éventuelleNon conservé

Principes appliqués

  • Le jeton d'interaction n'est jamais journalisé ni persisté sur disque.
  • Aucune donnée n'est extraite d'une requête dont la signature n'a pas été validée.
  • Les réponses contenant des données personnelles portent l'indicateur éphémère.
  • Les journaux applicatifs conservent l'identifiant de l'interaction et le nom de la commande, jamais le contenu des champs saisis.
  • Aucune donnée d'interaction n'est transmise à un tiers.

Dépannage

SymptômeCause probableRésolution
« Validation errors — interactions endpoint url »Le PING n'a pas reçu la réponse attendueVérifier le renvoi de {"type": 1} avec un code 200
Signature toujours invalideCorps re-sérialisé au lieu du corps brutConserver les octets originaux de la requête
Validation refusée malgré un PING correctLes signatures invalides ne reçoivent pas de 401Corriger le code de retour en cas d'échec
« L'application n'a pas répondu »Dépassement des trois secondesRépondre en type 5 puis compléter
Erreur 10062Réponse trop tardiveRéduire le temps de traitement, différer
Erreur 40060Double réponse initialeUne seule réponse initiale par interaction
Les commandes n'apparaissent pasCommandes non enregistrées ou propagation en coursEnregistrer au niveau du serveur pour un effet immédiat
Formulaire modal non affichéRéponse différée envoyée en premierLe type 9 doit être la première réponse
Erreur 401 côté DiscordEn-tête d'autorisation incorrectUtiliser le préfixe Bot avec le jeton
Interactions reçues en doubleAbsence de réponse dans le délai, réémissionRendre le traitement idempotent, répondre rapidement
Point de terminaison désactivé par DiscordÉchecs répétés de disponibilitéRétablir le service puis réenregistrer l'adresse

Référence rapide

Valeurs propres à ElSigm

ÉlémentValeur
Identifiant d'application1361056395524313158
Version d'API recommandéev10
Base de l'APIhttps://discord.com/api/v10
Route d'interactions suggérée/api/interactions
Mode de réception actuelPasserelle WebSocket
Intents privilégiés activésMessage Content, Server Members
Interactions Endpoint URLà laisser vide
Nombre de commandes déclarées24
Identifiants de composants utilisésgw_join, rp_report, rp_sb, sb_yes, sb_no, deban_btn, confirm_<id>

Constantes du protocole

ConstanteValeur
Algorithme de signatureEd25519
Longueur de la signature128 caractères hexadécimaux
Délai de réponse initiale3 secondes
Validité du jeton d'interaction15 minutes
Indicateur éphémère64
Longueur maximale d'un contenu2000 caractères
Embeds par message10 au maximum
Champs par embed25 au maximum
Rangées de composants5 au maximum
Boutons par rangée5 au maximum
Champs par formulaire modal5 au maximum
Longueur d'un custom_id100 caractères

Documents liés

La Politique de Confidentialité détaille le traitement des données mentionnées ici. Les Conditions d'Utilisation encadrent l'usage du service. La page Vérification des rôles liés documente le second point d'entrée HTTP de l'application, celui-là effectivement destiné à être exposé publiquement.