Webhook é um aviso que um sistema manda para outro quando algo acontece. No caso do GBBOT: quando um evento ocorre no seu servidor, o bot envia uma requisição para um endereço que você escolheu. Esse endereço pode ser uma automação no Zapier ou no n8n, um canal do Slack da sua equipe, ou um sistema seu.
É o que permite que o Discord deixe de ser uma ilha. O alerta de ataque chega no celular da equipe pelo canal que ela já usa; a entrada de membros vira linha numa planilha; a expiração do plano abre uma tarefa para alguém renovar.
Configurar leva poucos minutos. O que dá trabalho — e o que este guia cobre com calma — é o lado de quem recebe: validar que o aviso veio mesmo do GBBOT e lidar com o fato de que, às vezes, o mesmo aviso chega duas vezes.
Os eventos, e quando cada um dispara
| Evento | Quando é enviado |
|---|---|
| member.joined | alguém entrou no servidor |
| member.left | alguém saiu do servidor |
| raid.detected | a proteção contra ataques detectou uma entrada em massa |
| punishment.applied | a moderação automática aplicou uma punição |
| ticket.created / ticket.closed | um chamado com o suporte do GBBOT ligado ao servidor foi aberto ou fechado |
| license.expiring / license.expired | o plano do servidor está perto de vencer, ou venceu |
| test | você clicou em testar no painel |
Dois detalhes que evitam confusão. Punição aplicada à mão por um moderador, com comando, não gera o evento de punição: ele cobre a moderação automática. E os eventos de ticket se referem aos chamados abertos com o suporte do GBBOT, não aos tickets que seus membros abrem no painel de atendimento do seu servidor.
Configurando passo a passo
- 1
Decida o que você quer que aconteça fora do Discord
Comece por um caso só. "Quero ser avisado no Slack quando houver ataque" é um bom primeiro caso: tem um evento, um destino e um resultado fácil de conferir. Integração que começa com todos os eventos de uma vez vira um volume que ninguém olha.
- 2
Crie o receptor e copie o endereço
No Zapier ou no n8n, crie um fluxo que começa com o gatilho de webhook; a ferramenta gera um endereço. No Slack, crie um webhook de entrada no canal desejado. Em sistema próprio, é a rota que vai receber as requisições. Use sempre endereço com https.
- 3
Cadastre no painel e escolha os eventos
No painel do servidor, em Ferramentas, Webhooks. Cole o endereço, dê um nome que explique para que ele serve e marque só os eventos daquele caso. Cada servidor pode ter até 10 webhooks, então dá para ter um por destino em vez de um que recebe tudo.
- 4
Guarde o segredo de assinatura
Cada webhook tem um segredo próprio, usado para assinar as requisições. Guarde ele no receptor como senha, nunca no código público. Se ele vazar, gere outro pelo painel — o antigo deixa de valer.
- 5
Valide a assinatura no receptor
Toda requisição traz o cabeçalho X-GBBOT-Signature no formato sha256= seguido da assinatura. O receptor calcula a assinatura do corpo recebido com o segredo e compara. Se não bate, recusa. É o que impede alguém de mandar avisos falsos para o seu sistema fingindo ser o GBBOT.
- 6
Teste com o botão do painel
O botão de testar envia um evento de teste, e só chega se o evento de teste estiver marcado no webhook. Confira no receptor se chegou, se a assinatura validou e se o fluxo seguinte rodou. Depois disso, desmarque o evento de teste se não quiser recebê-lo mais.
O erro de validação mais comum
O cabeçalho de assinatura vem com o prefixo sha256= antes do valor. Quem compara a assinatura calculada direto com o cabeçalho inteiro vê toda requisição legítima ser recusada, e costuma concluir que o segredo está errado. Remova o prefixo antes de comparar, e calcule a assinatura sobre o corpo exatamente como chegou, antes de qualquer conversão — reformatar o JSON muda o resultado. A documentação em /docs/webhooks tem o exemplo pronto em Node e em Python.
Repetição: o receptor precisa aceitar o mesmo aviso duas vezes
Se o seu receptor demora mais de 5 segundos para responder, ou responde com erro de servidor, o GBBOT tenta de novo: depois de 1 segundo, de 4 e de 16, num total de quatro tentativas. Erro do tipo 4xx não é repetido, porque indica problema de configuração do seu lado, e insistir não resolveria.
A consequência é que o mesmo aviso pode chegar mais de uma vez — por exemplo, quando o seu sistema processou mas demorou para responder. Cada requisição traz um identificador de entrega e o número da tentativa nos cabeçalhos. Use o identificador para ignorar o que já foi processado. E responda rápido: devolva sucesso assim que receber e faça o trabalho pesado depois.
Depois de 10 falhas seguidas, o webhook é desativado automaticamente, para não ficar martelando um endereço que não existe mais. Corrija o receptor e reative pelo painel.
Usos que funcionam bem
- ●Alerta de ataque no Slack ou no grupo da equipe, para quem não fica com o Discord aberto.
- ●Planilha de entradas e saídas, útil para ver em que dias o servidor cresce e em que dias perde gente.
- ●Tarefa automática de renovação quando o plano está perto de vencer, para o servidor não perder recursos por esquecimento.
- ●Registro das punições automáticas num sistema de auditoria fora do Discord.
Configurar o webhook leva minutos. O trabalho de verdade está no receptor: validar a assinatura e aceitar que o mesmo aviso pode chegar duas vezes.
Perguntas frequentes
Preciso saber programar para usar webhooks?
Não necessariamente. Com Zapier ou n8n você monta o fluxo visualmente: o gatilho de webhook recebe o aviso e os passos seguintes fazem o resto. Programação só entra se o receptor for um sistema seu, e mesmo assim a documentação em /docs/webhooks traz o código de validação pronto.
Como sei que o aviso veio mesmo do GBBOT?
Pela assinatura. Cada requisição traz o cabeçalho X-GBBOT-Signature, calculado com um segredo que só você e o GBBOT conhecem. O receptor recalcula a assinatura sobre o corpo recebido, remove o prefixo sha256= do cabeçalho e compara. Se não bater, a requisição deve ser recusada.
Por que recebi o mesmo evento duas vezes?
Porque o receptor demorou mais de 5 segundos ou respondeu com erro, e o GBBOT tentou de novo. Cada requisição traz um identificador de entrega e o número da tentativa; use o identificador para ignorar o que já foi processado, e responda com sucesso assim que receber.
O webhook avisa quando um moderador bane alguém?
O evento de punição cobre as punições aplicadas pela moderação automática. Punição dada à mão, por comando, não gera esse evento. Se o que você quer é o registro de tudo o que a equipe faz, o canal de registro do servidor é a ferramenta certa.
Os tickets do meu servidor geram evento?
Não. Os eventos de ticket se referem aos chamados abertos com o suporte do GBBOT ligados ao servidor. Os tickets que seus membros abrem no painel de atendimento do seu servidor não disparam webhook hoje.
Quantos webhooks posso ter?
Até 10 por servidor. Vale usar um por destino, cada um com só os eventos que aquele destino precisa, em vez de um único webhook recebendo tudo. Fica mais fácil de entender, de testar e de desligar quando um destino deixar de existir.