Receba eventos do TicketWave como solicitações HTTP assinadas na sua própria aplicação.

Webhooks

Um webhook é uma solicitação HTTP que o TicketWave envia para você. Sempre que algo acontece no seu servidor — um ticket é aberto, um membro é colocado na blacklist — o TicketWave faz um POST de um corpo JSON para uma URL sua.

Essa é a diferença em relação aos Canais de Log: canais de log escrevem um embed no Discord para humanos lerem, enquanto os webhooks entregam o evento bruto ao seu código.

Webhooks são um recurso premium. Sem premium, endpoints não podem ser criados e nenhum evento é entregue.

Criar um Endpoint

Abra a página de endpoints

Painel do servidor → Webhooks → Endpoints.

Adicione um endpoint

Clique em Add Endpoint e preencha dois campos:

Field	Description
Endpoint URL	A URL `https://` que recebe as solicitações
Event Types	Quais eventos este endpoint deve receber

Um endpoint só recebe os tipos que você marcar. Não é permitido selecionar nenhum — escolha pelo menos um.

Copie o segredo de assinatura

O TicketWave gera um segredo de assinatura (whsec_…) no momento em que o endpoint é criado. Abra a lista de endpoints, revele-o com o ícone de olho e copie-o para a configuração da sua aplicação.

Trate o segredo como uma senha. Quem o tiver pode forjar solicitações que passam na verificação da assinatura. Guarde-o em uma variável de ambiente, nunca no seu repositório.

Envie um evento de teste

Use o botão Send test event (o avião de papel) na linha do endpoint. Ele entrega uma solicitação real, totalmente assinada, com "test": true no payload, para que você possa confirmar que o seu receptor funciona antes que um ticket real dependa disso.

O resultado aparece no histórico de Webhooks como qualquer outra entrega.

Requisitos do Endpoint

Requirement	Detail
Scheme	Apenas `https://` — `http://` é rejeitado
Host	Deve ser resolvível publicamente. Endereços privados, loopback, link-local e CGNAT são recusados
Response	Qualquer status `2xx` conta como sucesso
Timeout	Você tem 10 segundos para responder
Redirects	Não são seguidos. Um `3xx` conta como falha
Limit	Até 5 endpoints por servidor

A verificação do host acontece tanto quando você salva o endpoint quanto antes de cada entrega, então um domínio que depois passe a resolver para um endereço interno deixa de receber entregas.

A Solicitação

Toda entrega é um POST com um corpo JSON.

Headers

Header	Example	Meaning
`Content-Type`	`application/json`	Sempre JSON
`User-Agent`	`TicketWave-Webhooks/1.0.5`	A versão do bot que o enviou
`X-TicketWave-Event`	`ticket.created`	O tipo do evento
`X-TicketWave-Delivery`	`wh_3f2a…`	Id único desta entrega
`X-TicketWave-Timestamp`	`1786224191`	Segundos Unix, parte da assinatura
`X-TicketWave-Signature`	`sha256=9f86d0…`	HMAC da solicitação

Body

Todo payload usa o mesmo envelope. Apenas data muda conforme o tipo de evento:

{
  "event": "ticket.created",
  "timestamp": "2026-08-26T08:23:11.000Z",
  "guild_id": "123456789012345678",
  "data": {
    "ticket_id": "ticket-1042",
    "ticket_num_id": 1042,
    "channel_id": "998877665544332211",
    "category": "🤖 Support",
    "user": { "id": "987654321098765432", "username": "Luna" },
    "created_at": "2026-08-26T08:23:11.000Z"
  }
}

Veja a Referência de Eventos para o objeto data de cada tipo.

Verificando a Assinatura

Qualquer pessoa que descubra a URL do seu endpoint pode enviar uma solicitação POST para ele. A assinatura é como você distingue uma entrega real do TicketWave de uma forjada.

Verifique sempre. Um endpoint não verificado que cria ou encerra coisas no seu sistema é uma porta aberta.

Como a assinatura é construída

O TicketWave junta o timestamp e o corpo bruto da solicitação com um ponto, e executa HMAC-SHA256 sobre o resultado usando o segredo do seu endpoint:

signed_payload = X-TicketWave-Timestamp + "." + raw_request_body
signature      = HMAC_SHA256(signed_payload, your_endpoint_secret)

O header carrega esse digest em hexadecimal e com prefixo: sha256=<digest>.

O que o seu receptor deve fazer

Leia o corpo bruto. Verifique contra os bytes exatos que você recebeu. Se o seu framework analisar o JSON primeiro e você o reserializar, a ordem das chaves ou os espaços podem mudar e o digest não vai bater.

Recalcule o HMAC sobre timestamp + "." + rawBody com o seu segredo.

Compare em tempo constante (crypto.timingSafeEqual no Node). Um === simples vaza informação de tempo.

Verifique se o timestamp é recente — cinco minutos de tolerância é um bom padrão. O timestamp está dentro do payload assinado, então um atacante não pode reenviar uma solicitação antiga com um timestamp novo.

Uma implementação completa está na página Example Server.

Retries

Uma entrega que falha é reenviada automaticamente.


Attempts	3 (a primeira tentativa mais 2 retries)
Backoff	1 segundo, depois 5 segundos
Retried on	Erros de rede, timeouts, `408`, `429` e qualquer `5xx`
Not retried on	Qualquer outro `4xx` — isso significa que o seu endpoint rejeitou a solicitação de propósito

Por causa dos retries, o seu endpoint pode receber o mesmo evento duas vezes. Use X-TicketWave-Delivery como chave de idempotência: lembre-se dos ids que você já processou e ignore repetições.

As entregas não têm ordem. Se dois tickets forem criados ao mesmo tempo, as solicitações podem chegar em qualquer ordem — use o campo timestamp no corpo se a ordem importar para você.

Histórico de Entregas

A página Webhooks do painel lista todas as entregas com seu status, código de resposta, duração e número de tentativas. Abra uma linha para ver o payload exato da solicitação enviada e a resposta que o seu servidor retornou.

Entregas com falha podem ser reenviadas na página de detalhes com Retry Webhook. Isso envia o payload original novamente para o mesmo endpoint e registra uma nova entrega.

O histórico é mantido por 30 dias e depois é limpo automaticamente.

Solução de Problemas

Problem	Fix
O endpoint não pode ser salvo	A URL precisa ser `https://` e resolver para um endereço público
Tudo aparece como falha sem código de resposta	A solicitação nunca chegou até você — timeout, falha de DNS ou conexão recusada
A assinatura nunca bate	Você está fazendo hash do corpo analisado em vez dos bytes brutos, ou esqueceu o prefixo `timestamp + "."`
As entregas param depois de um tempo	Verifique se o seu host começou a retornar `4xx` — esses não são reenviados
Um evento nunca chega	O endpoint não está inscrito nesse tipo, ou o servidor perdeu o premium
Eventos duplicados	Esperado em retries — faça deduplicação com base em `X-TicketWave-Delivery`

Próximos Passos

Referência de Eventos (Todos os eventos e seus payloads)
Example Server (Um receptor Express executável)
Canais de Log (Os mesmos eventos, mas publicados no Discord)

Visão geral