Eventos (webhooks)

Com os eventos, a Catita avisa o seu bot quando algo acontece no servidor, sem ele precisar perguntar.

Configurar

Em /settings > API > Adicionar webhook, coloque a URL do seu bot (tem que ser https e pública). A Catita mostra o segredo de assinatura (whsec_…) uma vez: guarde. Até 3 webhooks por servidor.

Na tela do webhook você escolhe os eventos, testa com Testar (envia um ping), troca o segredo ou desliga.

Evento	Quando	data
level.up	Alguém sobe de nível	userId, instance, level, oldLevel
level.rebirth	Alguém faz rebirth	userId, instance, rebirths, level
streak.updated	Alguém avança a sequência	userId, instance, current, best
customrole.key_redeemed	Alguém resgata uma chave de cargo próprio	userId, key, days
economy.wallet_changed	A API muda uma carteira	userId, instance, amount, wallet, keyId

O que chega

Um POST com JSON:

{
  "id": "6f1c…",
  "type": "level.up",
  "guildId": "111111111111111111",
  "createdAt": "2026-11-04T18:00:00.000Z",
  "data": { "userId": "123456789012345678", "instance": "1", "level": 12, "oldLevel": 11 }
}

Com estes cabeçalhos:

• Catita-Event: o tipo.
• Catita-Delivery: o id do evento (se chegar duas vezes, ignore o repetido).
• Catita-Timestamp: segundos Unix do envio.
• Catita-Signature: v1= e o HMAC-SHA256 em hexadecimal de <timestamp>.<corpo> com o seu segredo.

Responda com um 2xx em menos de 5 segundos. Se falhar, a Catita tenta mais 5 vezes com espera crescente (10 s, 20 s, 40 s…). Depois de 25 falhas seguidas, desliga o webhook e avisa no canal de registros. Redirecionamentos não são seguidos.

Conferir a assinatura

Confira sempre a assinatura e se a hora é recente, para saber que o aviso é da Catita:

const crypto = require('node:crypto');
const express = require('express');

const app = express();

app.post('/catita', express.raw({ type: 'application/json' }), (req, res) => {
    const timestamp = req.get('Catita-Timestamp');
    const given = req.get('Catita-Signature') || '';
    const expected = 'v1=' + crypto
        .createHmac('sha256', process.env.CATITA_WEBHOOK_SECRET)
        .update(`${timestamp}.${req.body}`)
        .digest('hex');

    const fresh = Math.abs(Date.now() / 1000 - Number(timestamp)) < 300;
    const valid = given.length === expected.length && crypto.timingSafeEqual(Buffer.from(given), Buffer.from(expected));
    if (!fresh || !valid) return res.sendStatus(401);

    const event = JSON.parse(req.body);
    if (event.type === 'level.up') {
        console.log(`${event.data.userId} chegou ao nível ${event.data.level}`);
    }
    res.sendStatus(204);
});

app.listen(3000);

Use o corpo exatamente como chega (sem converter de novo para JSON), senão a assinatura não bate.