Webhooks

Um webhook é um aviso que o Dashboard Mágico manda para o seu sistema quando algo acontece — por exemplo, quando um token de API é revogado. Em vez de o seu sistema perguntar de tempos em tempos, ele recebe um POST com os dados do evento assim que o evento acontece. O endereço que recebe esse POST é o endpoint.

Os endpoints ficam na aba Webhooks de Sistema › API (/dashboard/api?tab=webhooks).

No topo, quatro números resumem o workspace: endpoints Ativos e Inativos, Entregas Totais e Falhas. Abaixo vem a Lista de Webhooks, com filtro por status e busca por URL, e depois os Logs de Entrega.

Endpoints e workspaces

Cada endpoint pertence ao workspace em que foi criado, e a lista mostra só os do workspace ativo. Os eventos de um workspace chegam apenas aos endpoints dele; os eventos da organização como um todo chegam aos endpoints de todos os workspaces.

Criar um endpoint

1. Na Lista de Webhooks, clique em Novo Webhook.

2. Preencha os campos:

   Campo	O que é
   URL do Endpoint	O endereço que recebe os eventos. Precisa ser https:// e público: endereços internos ou privados (como localhost) são recusados.
   Autenticação	Uma credencial que o Dashboard Mágico envia em cada requisição, se o seu endpoint exigir: Nenhuma, Basic Auth (usuário e senha), Bearer Token ou Cabeçalho Customizado (nome e valor). Fica guardada criptografada.
   Descrição (opcional)	Para lembrar quem usa o endpoint — por exemplo, ERP — atualizações de portal e usuários.
   Eventos	Os eventos que o endpoint quer receber. Marcar todos seleciona os de uma categoria de uma vez. Veja Eventos de webhook.

3. Clique em Criar Webhook.

4. O Dashboard Mágico mostra o secret do endpoint. Copie e guarde num lugar seguro: ele não aparece de novo. Clique em Salvei.

Marque pelo menos um evento: o endpoint recebe só os eventos marcados.

O que dá para fazer com um endpoint

Onde	Ação	O que acontece
Coluna Status	Chave liga/desliga	Desligado, o endpoint para de receber eventos. Ligue de novo quando quiser.
Coluna Entregas	Clique no número	Abre o histórico de entregas daquele endpoint.
Menu ⋯	Visualizar	Mostra a URL, a autenticação e os eventos.
Menu ⋯	Editar	Muda a autenticação, a descrição e os eventos. A URL não muda: para outro endereço, crie outro endpoint. Para trocar uma credencial, preencha-a de novo.
Menu ⋯	Testar Webhook	Envia um evento de teste (test.webhook), assinado como os reais, e mostra se o endpoint respondeu com sucesso. O teste aparece nos logs de entrega.
Menu ⋯	Rotacionar Secret	Gera um secret novo, mostrado uma única vez. O antigo para de valer na hora: atualize o seu sistema logo em seguida.
Menu ⋯	Excluir	Remove o endpoint e o histórico de entregas dele. Não tem volta.

Como o seu sistema confere que o aviso é do Dashboard Mágico

Cada entrega é assinada com o secret do endpoint. O seu sistema recalcula a assinatura com o mesmo secret e compara: se bater, o aviso veio mesmo do Dashboard Mágico e não foi alterado no caminho.

A assinatura segue o padrão Standard Webhooks e vai nos headers webhook-signature e X-Kobana-Signature. Em resumo, o seu sistema deve:

1. Ler os headers webhook-id, webhook-timestamp e webhook-signature.
2. Recusar a entrega se o horário estiver a mais de 5 minutos do relógio atual.
3. Calcular o HMAC-SHA256 de webhook-id + . + webhook-timestamp + . + o corpo exatamente como recebido, com a chave do secret.
4. Comparar o resultado com a assinatura recebida.

O passo a passo, com exemplos em Node.js e Python e a lista completa de headers, está na referência de webhooks da API.

Desativação automática

Se um endpoint falha 10 vezes seguidas, o Dashboard Mágico desliga o endpoint sozinho, para não ficar insistindo. Corrija o problema no seu sistema, use Testar Webhook para conferir e ligue a chave da coluna Status de novo. Uma entrega bem-sucedida zera a contagem de falhas.

Toda criação, alteração, teste, rotação de secret e exclusão de endpoint fica registrada em Auditoria.