Webhooks do app

Um webhook de app é uma URL por canal para a qual o seu runner de CI, sua ferramenta de monitoramento ou um serviço externo pode fazer POST para deixar uma mensagem em um canal do GameVox. Sem sessão de gateway. As mensagens saem como o seu usuário bot, com o avatar e o nome dele.

Limites

50 webhooks por aplicação.
Nome: 1 a 80 caracteres.
Conteúdo: 1 a 4000 caracteres por mensagem.
Um webhook = um canal. Criar um webhook exige a permissão manage_server no servidor do canal.

Formato do token

WH.{prefixo de 8 caracteres}.{aleatório em base64}

exemplo: WH.aB7xZ2k1.q9F7v1NkN3J2Wm8L6PpV5cU0Yr1zQbXa

O token completo é exibido exatamente uma vez, na criação. Guardamos apenas o hash bcrypt mais o prefixo e os 4 últimos caracteres para exibição. Se você perder um token, exclua o webhook e crie outro.

Criando um webhook (portal)

Abra sua aplicação → aba Webhooks → Novo webhook. Escolha um servidor que você gerencia, escolha um canal e dê um nome. A janela mostra o token completo e a URL de execução pronta para colar. Copie antes de fechar; o portal nunca mostrará de novo.

Endpoints

Dois modos de autenticação: token do bot para gerenciamento, token na URL para execução.

Autenticação por token de bot (gerenciamento)

GET    /channels/{channel.id}/webhooks
POST   /channels/{channel.id}/webhooks
GET    /guilds/{guild.id}/webhooks
GET    /webhooks/{webhook.id}
PATCH  /webhooks/{webhook.id}
DELETE /webhooks/{webhook.id}

Autenticação por token na URL (executar + editar)

POST   /webhooks/{webhook.id}/{token}
GET    /webhooks/{webhook.id}/{token}
PATCH  /webhooks/{webhook.id}/{token}
DELETE /webhooks/{webhook.id}/{token}
PATCH  /webhooks/{webhook.id}/{token}/messages/{message.id}
DELETE /webhooks/{webhook.id}/{token}/messages/{message.id}

Nas rotas com token na URL não existe cabeçalho Authorization. O token no caminho é a autenticação. Trate a URL como um segredo.

Requisição de execução

Corpo JSON:

POST https://api.gamevox.com/webhooks/{webhook.id}/{token}
Content-Type: application/json

{
  "content": "A build #4811 passou em produção.",
  "embeds": [
    {
      "title": "CI no verde",
      "url": "https://ci.example.com/builds/4811",
      "description": "42 testes, 0 falhas.",
      "color": 3066993
    }
  ]
}

Corpo multipart/form-data (para anexos):

Content-Type: multipart/form-data; boundary=xyz

--xyz
Content-Disposition: form-data; name="payload_json"

{ "content": "Veja a captura", "embeds": [ ... ] }
--xyz
Content-Disposition: form-data; name="files[0]"; filename="crash.png"
Content-Type: image/png

...binary...
--xyz--

Resposta (nos dois tipos de conteúdo):

{
  "id": "1199283740192847400",
  "channel_id": "1199283740192847000",
  "content": "A build #4811 passou em produção.",
  "embeds": [ ... ],
  "attachments": [ ... ],
  "timestamp": "2026-05-21T15:42:09Z"
}

O que é suportado

Conteúdo: texto puro, 1 a 4000 caracteres.
Embeds: formato completo de embed do Discord (title, description, url, color, timestamp, footer, image, thumbnail, author, fields). Vários embeds por mensagem são permitidos.
Anexos: envie arquivos por multipart/form-data com uma parte payload_json; a resposta inclui URLs de CDN.
Responder a uma mensagem: passe message_reference em payload_json.
?wait=true: implícito; a resposta é sempre a mensagem resolvida.
Editar / excluir: PATCH / DELETE em /webhooks/{id}/{token}/messages/{message.id} espelham o Discord.
Sobrescrever nome ou avatar: não é suportado. As mensagens sempre saem como o usuário bot da aplicação.

Erros

401: token ausente, malformado ou que não confere.
404: webhook excluído, ou id inexistente.
400: content vazio sem embeds nem anexos, ou content com mais de 4000 caracteres.
405: verbo não suportado nesta rota.
413: o anexo excede o limite de tamanho por arquivo.

Rotação

Não há endpoint de rotação no lugar na v1. Exclua o webhook e crie outro. O token antigo para de funcionar imediatamente após a exclusão (o caminho de execução ignora linhas com exclusão lógica).

Diferenças em relação ao Discord

Os webhooks pertencem à aplicação, não à administração do servidor. Excluir o canal não exclui o registro do webhook; a execução seguinte devolve 404 por causa do join com o canal na consulta.
Sem sobrescrita de username / avatar_url por requisição. A identidade é fixa no usuário bot.
Não há teto por canal; o teto é por aplicação (50).
A autenticação é verificada com bcrypt, então a comparação do token é propositalmente lenta. Não martele o endpoint em laços apertados.
Servidores auto-hospedados: os webhooks não são encaminhados para instâncias auto-hospedadas. Todos os endpoints de webhook devolvem 404 para destinos de guild auto-hospedados. Veja a documentação de auto-hospedagem.

← Voltar para a documentação