Gerenciar Webhooks (Guia do Administrador)

Este guia explica como administradores da GDREdu gerenciam webhooks — criar, editar, testar, rotacionar secret, desativar e consultar o histórico de entregas — diretamente pelo painel administrativo, sem precisar consumir a API.

Pré-requisitos

Para acessar a tela de Webhooks, você precisa ter uma das seguintes permissões (role) em pelo menos uma unidade:

• DASH_ADMIN — Administrador do painel
• DASH_MANAGER — Gestor do painel

Se você não vê a opção "Webhooks" no menu lateral, entre em contato com o administrador da instituição.

Acessando a tela

1. Faça login no painel da GDREdu.
2. No menu lateral, vá em Gestão → Webhooks (ou /dashboard/webhooks).

A tela lista todos os webhooks configurados em todas as unidades da instituição. Use o filtro de unidade e a busca por URL para localizar rapidamente.

Criando um Webhook

1. Clique no botão "Novo Webhook" no canto superior direito.
2. Preencha o formulário:

3. Clique em "Criar Webhook".
4. Importante: O secret (formato whsec_...) será exibido apenas uma vez em uma janela de confirmação.
5. Copie o secret imediatamente e armazene-o em local seguro (cofre de senhas, variável de ambiente, etc.) — você precisará dele para validar a assinatura HMAC dos eventos.
6. Clique em "Já copiei, fechar".

:::danger
O secret completo do webhook não pode ser recuperado após fechar a janela. Apenas um prefixo (ex: whsec_3f8a9b2c) permanece visível na listagem para identificação. Se o secret for perdido, use a ação Rotacionar secret no painel para gerar um novo.
:::

Listando Webhooks

A tela principal mostra todos os webhooks da instituição em uma tabela paginada com:

• Unidade — nome da filial + prefixo do secret
• URL — endpoint configurado (truncado; passe o mouse para ver completo)
• Eventos — badges com os eventos habilitados
• Última entrega — data/hora da última tentativa + HTTP status
• Entregas — total de entregas registradas (clicável, abre o histórico)
• Status — Ativo ou Desativado

Use a barra de busca para filtrar por URL e o seletor de unidades para ver apenas uma filial.

Editando um Webhook

Permite alterar URL, eventos e status ativo/inativo sem precisar recriar o webhook.

1. Na linha do webhook, clique no ícone de lápis.
2. Atualize os campos desejados.
3. Clique em "Salvar alterações".

:::info
A edição não altera o secret. Para trocar o secret, use a ação Rotacionar secret.
:::

Disparando um evento de teste

Útil para validar a configuração da URL receptora, a validação da assinatura HMAC e a conectividade antes de depender dos eventos reais.

1. Na linha do webhook, clique no ícone de raio.
2. O painel dispara um evento equipment.recognized de teste em tempo real (sem passar pela fila assíncrona).
3. O resultado aparece inline com:
   • Status da entrega (Sucesso / Reagendando / Ignorado)
   • HTTP status da resposta do receptor
   • Duração em milissegundos
   • Corpo da resposta (colapsável)
   • Erro (se houver)
4. Use "Disparar novamente" para repetir.

A entrega também fica registrada em Histórico de entregas com o deliveryId correspondente, permitindo correlacionar com logs do receptor.

:::info
O teste é executado de forma síncrona a partir do painel — diferentemente do fluxo real, que passa pela fila assíncrona do backend. A assinatura HMAC, formato do payload e headers são idênticos.
:::

Rotacionando o secret

Rotação gera um novo secret para o webhook, mantendo o mesmo ID, unidade, URL e eventos. O secret anterior deixa de funcionar imediatamente.

1. Na linha do webhook, clique no ícone de rotação (setas circulares).
2. Confirme a operação na janela de confirmação.
3. Copie o novo secret exibido — ele também é mostrado apenas uma vez.
4. Atualize suas integrações com o novo secret.

:::warning
Rotação invalida o secret anterior. Ao rotacionar, todas as integrações que validavam a assinatura HMAC com o secret anterior passarão a falhar a verificação. Coordenar a rotação com a atualização do secret no receptor.
:::

:::tip
A rotação de secret está disponível apenas no painel. Via API, o secret não pode ser alterado por PUT — é necessário desativar o webhook e criar um novo.
:::

Desativando um Webhook

Desativação é uma exclusão lógica (soft): o webhook deixa de receber eventos imediatamente, mas o registro e seu histórico de entregas são preservados.

1. Na linha do webhook ativo, clique no ícone de lixeira.
2. Confirme a operação na janela de confirmação.
3. O webhook muda para o status Desativado e nenhum evento será mais entregue.

:::info
Para recriar um webhook em uma unidade que já possui um (mesmo desativado), é necessário primeiro entrar em contato com o suporte para limpar o registro.
:::

Histórico de entregas

Toda tentativa de entrega (real ou teste) é registrada em WebhookDelivery e pode ser consultada pelo painel.

1. Na linha do webhook, clique no número na coluna Entregas.
2. A modal mostra as últimas 50 entregas em ordem decrescente:

Boas práticas administrativas

1. HTTPS sempre que possível: prefira URLs https:// para garantir confidencialidade do payload em trânsito.

2. Valide a assinatura HMAC: rejeite qualquer requisição em que X-GDREdu-Signature não seja válida. Veja Assinatura HMAC.

3. Responda rápido (≤ 30s): cada tentativa tem timeout de 30s. Respostas lentas geram retentativas desnecessárias.

4. Um webhook por unidade: não crie múltiplos webhooks para a mesma filial — o sistema permite apenas 1. Para distribuir eventos, use lógica no receptor.

5. Rotacione periodicamente: rotacione o secret a cada 6-12 meses, ou imediatamente se houver indício de exposição.

6. Monitore o histórico: entregas com status RETRYING ou IGNORED recorrentes indicam problema no receptor. Investigue.

7. Use a ação de teste antes de ir para produção: sempre dispare um evento de teste após criar ou editar um webhook para confirmar que o receptor está pronto.

Próximos passos

• Visão geral de Webhooks — Como funciona o sistema de webhooks
• Assinatura HMAC — Como validar a autenticidade dos eventos
• Exemplo de receptor — Código completo em Node.js
• Política de retentativas — Backoff e limites de tentativas