Logs FiveM sur Discord : la mise en place, étape par étape.

Étape 1 : créer le webhook dans Discord

Ouvrez les Paramètres du serveur Discord, allez dans l’onglet Intégrations et cliquez sur Créer un webhook. Donnez-lui un nom que votre staff reconnaîtra, par exemple Logs serveur, choisissez le salon textuel où il poste, puis cliquez sur Copier l’URL du webhook. Il faut la permission Gérer les webhooks sur le serveur.

Créez un webhook par salon de logs : connexions et déconnexions dans l’un, actions admin dans un autre, économie dans un troisième. Chaque webhook est lié à un seul salon : c’est l’URL utilisée par votre script qui décide où le message arrive.

Traitez cette URL comme un mot de passe. Quiconque la possède peut poster dans le salon, sans bot ni compte. Si elle fuite, dans une capture d’écran ou un dépôt public par exemple, supprimez le webhook depuis la même page Intégrations et créez-en un nouveau.

Étape 2 : ranger l’URL dans le server.cfg, pas dans un script

Mettez l’URL dans une convar déclarée avec set. Une convar set reste sur le serveur : les scripts client ne peuvent pas la lire. N’utilisez pas setr, qui réplique la valeur à chaque joueur connecté, et ne collez jamais une URL de webhook dans un script client ou une page NUI, où n’importe qui peut la récupérer dans ses fichiers de jeu.

Garder l’URL dans le server.cfg permet aussi de la changer sans toucher à une ressource. Attention : le server.cfg n’est lu qu’au démarrage du serveur, et le script ci-dessous lit la convar une seule fois, au chargement de la ressource. Modifiez donc la ligne dans le server.cfg pour le prochain redémarrage, puis appliquez-la tout de suite en tapant la même ligne set dans la console du serveur (ou la console live de txAdmin) et en redémarrant la ressource qui la lit.

set discord_logs_webhook "https://discord.com/api/webhooks/<id>/<token>"

Étape 3 : poster un embed depuis un script serveur

Dans un fichier Lua côté serveur, lisez la convar avec GetConvar et envoyez une requête POST avec PerformHttpRequest. Le point d’accès Execute Webhook de Discord prend un corps JSON avec content (du texte, jusqu’à 2000 caractères) ou embeds (jusqu’à 10 par message), et un username optionnel qui remplace le nom du webhook. Un embed a un title, une description et une color sous forme d’entier.

L’exemple ci-dessous poste un embed rouge chaque fois qu’un joueur quitte le serveur, grâce à l’événement playerDropped et à sa raison. Réutilisez discordLog dans le reste de votre code serveur pour les bans, les mouvements d’argent ou les commandes admin. Discord répond avec un statut 2xx quand le message est accepté : le callback affiche tout le reste dans la console au lieu d’échouer en silence.

local webhook = GetConvar('discord_logs_webhook', '')

local function discordLog(title, description, color)
    if webhook == '' then return end
    PerformHttpRequest(webhook, function(status, body)
        if status < 200 or status >= 300 then
            print(('discord log failed: %s %s'):format(status, body or ''))
        end
    end, 'POST', json.encode({
        username = 'Logs serveur',
        embeds = { { title = title, description = description, color = color } },
    }), { ['Content-Type'] = 'application/json' })
end

AddEventHandler('playerDropped', function(reason)
    discordLog('Joueur parti', GetPlayerName(source) .. ' (' .. reason .. ')', 15158332)
end)

Les limites à connaître avant que le salon déborde

Les embeds ont des limites strictes : 256 caractères pour un titre, 4096 pour une description, 1024 pour la valeur d’un champ et 6000 pour l’ensemble d’un message. Coupez les textes longs, comme des messages de chat ou des contenus d’inventaire, avant l’envoi, sinon Discord refuse le message entier.

Discord limite aussi le débit des requêtes. Si vous envoyez trop vite, il répond HTTP 429 avec une valeur retry_after en secondes, et sa documentation demande de lire cette valeur plutôt que de coder un délai en dur. La fonction ci-dessus ne réessaie pas : une rafale, comme un redémarrage qui déconnecte tout le monde d’un coup, peut faire perdre des messages. Regrouper plusieurs événements dans un même message (jusqu’à 10 embeds) aide.

Par défaut, les messages de webhook ne transforment en notification que les mentions d’utilisateurs, pas celles de rôles ni everyone, mais Discord peut retirer certains caractères de ce que vous envoyez. Les pseudos et le chat sont saisis par les joueurs : ne comptez pas les voir apparaître exactement tels quels.

Quand un salon Discord ne suffit plus comme historique

Pour un petit serveur, la mise en place ci-dessus suffit et ne coûte rien. Les ennuis arrivent avec le volume. Au bout de quelques mois, un salon de logs contient des dizaines de milliers de messages, la recherche Discord ne sait pas filtrer sur un champ, comme les montants au-dessus d’une valeur ou tous les événements d’une license, et l’historique n’est complet que si vos envois ont tous réussi. Retrouver tout ce qu’a fait un joueur dans cinq salons devient une corvée.

La solution habituelle : stocker les logs dans un outil où l’on peut chercher, et garder Discord pour les moments où un humain doit regarder. BasiX est une façon de le faire. Installez la ressource basix, mettez une clé limitée à l’upload dans le server.cfg (elle fonctionne sur toutes les offres, y compris la gratuite, où une clé complète est refusée) et appelez exports.basix:info, warn ou error avec un joueur et des métadonnées. Les événements sont regroupés et envoyés toutes les deux secondes, et jusqu’à 400 sont gardés en mémoire si l’API est injoignable. Toutes les offres stockent et permettent de chercher dans les logs, y compris la gratuite, qui les garde 3 jours ; Starter les garde 30 jours.

Discord ne reçoit alors que les alertes. Dans le tableau de bord, ouvrez Logs, puis la page des catégories, vues et alertes, créez une nouvelle règle d’alerte et collez l’URL de votre webhook Discord. Une règle se déclenche quand un nombre d’événements correspondants (par niveau, texte, métadonnée ou catégorie) arrive dans une fenêtre de temps, puis reste silencieuse pendant un délai choisi : une rafale donne un message au lieu de cinquante. Les règles d’alerte ne sont pas comprises dans l’offre gratuite : 5 avec Starter (5 € par mois) et 20 avec Pro, que vous pouvez essayer gratuitement pendant 14 jours.

set basix_key "bx_live_yourkeyhere"
ensure basix

exports.basix:warn('Suspicious money add', {
    player = GetPlayerIdentifierByType(source, 'license'),
    metadata = { amount = 999999, source = 'admin' },
})