Logs de webhook Discord de um servidor FiveM: guia PerformHttpRequest

Você quer saber quem comprou o quê, quem deu dinheiro, quem executou um comando de admin e quem entrou, sem observar o console o dia todo. Um webhook Discord faz isso: seu servidor envia uma mensagem para um canal. Este guia mostra o Lua do lado do servidor com PerformHttpRequest, como construir embeds, como manter a URL segura e como evitar o rate limit.

#Crie o webhook

No Discord, abra as configurações do canal, depois Integrações, depois Webhooks, crie um e copie sua URL. Parece https://discord.com/api/webhooks/<id>/<token>. Qualquer um com essa URL pode postar no seu canal, então trate-a como uma senha.

#Mantenha a URL em uma convar

Coloque em server.cfg:

set discord_webhook_logs "https://discord.com/api/webhooks/ID/TOKEN"

Use set, não setr ou sets. Uma convar replicada é enviada para cada cliente, o que vazaria a URL. Leia-a no servidor:

local WEBHOOK = GetConvar('discord_webhook_logs', '')

Se a convar estiver vazia, pule enviando em vez de errar. Você pode manter uma convar por tipo de log (dinheiro, admin, entradas) para enviá-las para canais diferentes.

#Envie uma mensagem

local function sendLog(title, description, color, fields)
    if WEBHOOK == '' then return end

    local embed = {
        title = title,
        description = description,
        color = color or 3447003,
        fields = fields,
        timestamp = os.date('!%Y-%m-%dT%H:%M:%SZ'),
    }

    PerformHttpRequest(WEBHOOK, function(status, body, headers)
        if status ~= 204 and status ~= 200 then
            print(('webhook failed: %s'):format(status))
        end
    end, 'POST', json.encode({ username = 'Server logs', embeds = { embed } }), {
        ['Content-Type'] = 'application/json',
    })
end

Pontos a saber:

• color é um número decimal, não uma string hex. 3447003 é azul e 15158332 é vermelho. Converta hex com tonumber('FF0000', 16).
• timestamp deve ser uma data ISO 8601 em UTC. O ! no formato faz os.date usar UTC.
• fields é uma lista de { name = '...', value = '...', inline = true }. Um valor de field não pode estar vazio.
• Uma chamada webhook bem-sucedida retorna status 204, com um corpo vazio.
• Discord limita tamanhos. Títulos são curtos (256 caracteres), descrições são longas mas limitadas (4096), e uma mensagem contém um número limitado de fields e embeds. Corte texto longo antes de enviar.

Um exemplo de chamada, para um jogador que enviou dinheiro:

sendLog('Money transfer', 'A player sent money', 3066993, {
    { name = 'From', value = ('%s (id %d)'):format(GetPlayerName(src), src), inline = true },
    { name = 'To', value = ('%s (id %d)'):format(GetPlayerName(target), target), inline = true },
    { name = 'Amount', value = ('$%d'):format(amount), inline = false },
})

#Apenas lado do servidor, nunca do cliente

Atenção: não chame PerformHttpRequest para um webhook em um script cliente, e não envie a URL para o cliente. Arquivos cliente podem ser lidos por cada jogador, então a URL vaza e qualquer um pode inundar seu canal.

Se um evento no cliente deve ser registrado, envie um evento para o servidor, e deixe o servidor decidir o que registrar de dados que confia. Um cliente que pode disparar "log this text" também pode disparar logs falsos. Para segurança de eventos em geral, leia secure events in FiveM. Registre o que o servidor fez, não o que o cliente diz que fez.

#Rate limits: use uma fila

Discord rejeita chamadas de webhook que chegam muito rápido, com uma resposta 429. Uma explosão de logs, como 50 jogadores disparando o mesmo evento, pode acertá-la. Envie as mensagens de uma fila em um ritmo constante:

local queue = {}

local function enqueue(payload)
    queue[#queue + 1] = payload
end

CreateThread(function()
    while true do
        local item = table.remove(queue, 1)
        if item then
            PerformHttpRequest(WEBHOOK, function(status, _, headers)
                if status == 429 then
                    -- put it back and wait a bit longer
                    table.insert(queue, 1, item)
                    Wait(5000)
                end
            end, 'POST', json.encode(item), { ['Content-Type'] = 'application/json' })
        end
        Wait(2000)
    end
end)

Esperar dois segundos entre mensagens fica sob o limite. Se você precisa mais, agrupe vários embeds em uma mensagem: uma request pode levar até 10 embeds em sua lista embeds. Para o uso de Wait, veja Wait explained.

#O que registrar

Registre os eventos que você gostaria quando algo dá errado:

• Dinheiro: transferências grandes, compras, qualquer coisa que crie dinheiro. Isto é onde abuso mostra primeiro.
• Ações de admin: quem usou qual comando de admin em quem, bans, avisos, teleports. Veja ban and warn players.
• Entradas e saídas, com os identificadores do jogador, o que ajuda com disputas e bans.
• Spawning de item e uso de arma, se você as permite.

Não registre tudo. Um canal com uma mensagem a cada segundo é um canal que ninguém lê. Escolha alguns canais, coloque os importantes onde staff olha, e mantenha o resto curto. Mantenha dados pessoais ao que você precisa, e não registre chat privado.

Dica: coloque sua função de logging em um pequeno recurso e chame-a com uma export de seus outros scripts, para que a URL do webhook e a fila de rate limit vivam em um lugar. Veja exports in FiveM.

#Checklist