/patrimonio/integracoes/webhooks · "Configurações" → cartão "Webhooks"integration.read ("Ver integrações") — lista e log de entregas. Cadastrar, testar, rotacionar o segredo, pausar/reativar, excluir e reenviar exigem webhook.manage ("Gerenciar webhooks"); os botões aparecem para todos, mas sem a chave o servidor recusa.Para que serve
Avisar automaticamente outro sistema quando algo acontece no acervo (bem criado, movimentação concluída, inventário encerrado, baixa concluída…). Cada aviso é enviado ao endereço cadastrado com uma assinatura feita com um segredo, para o destino conferir que veio mesmo do Patrimônio. Entrega que falha é tentada de novo; 50 falhas seguidas desativam o endereço.
A tela, marcação por marcação
As figuras abaixo mostram a tela como ela aparece para quem usa. Os números em vermelho marcam os botões e campos; logo abaixo de cada figura, cada número é explicado: onde fica, o que faz e o que acontece depois.
Visão geral da tela

- Abre a janela "Novo endpoint".
- O que faz: manda um aviso de teste assinado. Balão verde "O destino respondeu <código>. A assinatura foi aceita." ou laranja "O destino respondeu <código | nada>. Veja o log de entregas."
- Abre o painel lateral "Entregas de <nome>".
- Pede confirmação? Sim — "Rotacionar o segredo do webhook": "Um segredo novo é gerado para <nome> e o atual deixa de valer na mesma hora. Até o sistema de destino receber o novo segredo, ele vai recusar a assinatura dos avisos." Botão vermelho "Rotacionar".
- O que faz: mostra o segredo novo na janela "Segredo do webhook" (única vez).
- O que faz: suspende ou retoma os envios para o endereço. Sem confirmação. "Reativar" também serve para religar um endpoint "Desativado por falhas".
- Pede confirmação? Sim — "Excluir webhook": "o webhook <nome> (<endereço>)", com "os avisos para este endereço param de ser enviados" e "o segredo de assinatura deixa de valer".
- Se der errado: "Endpoint de webhook não encontrado."
Webhook pausado

Abre a janela "Novo endpoint".
Explicado em detalhes na Figura 1.
O que faz: manda um aviso de teste assinado. Balão verde "O destino respondeu <código>. A assinatura foi aceita." ou laranja "O destino respondeu <código | nada>. Veja o log de entregas."
Explicado em detalhes na Figura 1.
Abre o painel lateral "Entregas de <nome>".
Explicado em detalhes na Figura 1.
O que faz: mostra o segredo novo na janela "Segredo do webhook" (única vez).
Explicado em detalhes na Figura 1.
O que faz: suspende ou retoma os envios para o endereço. Sem confirmação. "Reativar" também serve para religar um endpoint "Desativado por falhas".
Explicado em detalhes na Figura 1.
Pede confirmação? Sim — "Excluir webhook": "o webhook <nome> (<endereço>)", com "os avisos para este endereço param de ser enviados" e "o segredo de assinatura deixa de valer".
Explicado em detalhes na Figura 1.
Como a tela está organizada (de cima para baixo)
- Cabeçalho — caminho "Integrações › Webhooks", título "Webhooks", subtítulo "Para onde o módulo avisa quando algo acontece no acervo." À direita, "Novo endpoint" (ícone de tomada) — só para quem tem
webhook.manage; sem ela também não aparecem ping, rotacionar, "Pausar"/"Reativar", excluir e "Reenviar" (fica "Ver entregas"). A tabela rola dentro do cartão no celular. - Faixa laranja (quando há problema) — "Um endpoint está / N endpoints estão com falhas. Enquanto não voltarem, o sistema do outro lado deixa de saber o que acontece aqui."
- Tabela — "Endpoint" (nome e endereço), "Eventos" (selos), "Entregas" ("N entregues · N descartadas"), "Situação" ("Entregando" verde, "N falha(s) recente(s)" amarelo, "N falhas seguidas" laranja, "Pausado" cinza, "Desativado por falhas" vermelho — com o motivo embaixo) e os botões da linha. Vazio: "Nenhum endpoint cadastrado."
- Nota — "Entrega que falha é tentada de novo em 1 min, 5 min, 30 min, 120 min, 720 min. Depois disso a entrega é descartada, e 50 falhas seguidas desativam o endpoint — com aviso a quem administra integrações."
Botões
Os botões marcados nas figuras estão explicados junto de cada figura (seção “A tela, marcação por marcação”). Não há outros botões nesta tela.
Janelas
"Novo endpoint"

Fecha a janela sem gravar nada; a tela de trás continua como estava.
- Botões: "Cancelar" · "Cadastrar".
- Campos: "Nome" (ex.: "Painel do gabinete"; mínimo 3 caracteres — "Diga qual sistema recebe.") · "Endereço" — "Só https, e nunca para um endereço da rede interna." (começa com "https://"; "O endereço precisa ser https.") · "Eventos" — caixas com o nome técnico e a descrição: asset.created, asset.updated, asset.status_changed, movement.completed, inventory.campaign.closed, disposal.concluded, depreciation.run.completed, custody.term.signed, approval.decided, maintenance.order.completed (ao menos um: "Escolha ao menos um evento.").
- Botões: "Cancelar" · "Cadastrar".
- Efeito: abre a janela "Segredo do webhook".
- Mensagens do servidor ("Endereço recusado: …"): "O endereço precisa começar com https://." · "Só as portas 443 e 8443 são aceitas." · "O endereço aponta para a própria máquina do servidor." · "O endereço aponta para uma faixa de rede interna." · "O endereço aponta para uma faixa de uso local do enlace." · "O endereço aponta para o serviço de metadados da nuvem." · "O endereço está numa faixa reservada e não pode ser alcançado." · "Não coloque usuário e senha no endereço; use o segredo do webhook." · "Um endpoint sem evento nunca receberia nada."
"Segredo do webhook" (mostrado uma vez)

- Mostra: "Copie agora. Este valor não será exibido novamente…", a instrução "Use este segredo para conferir o cabeçalho X-Patrimonio-Signature de cada entrega. A assinatura é um HMAC-SHA256 do corpo da entrega com este segredo; quem mantém o sistema de destino sabe usá-la." e o segredo.
- Botões: "Copiar"/"Copiado" · "Já guardei, pode fechar" (não fecha clicando fora).
- Mostra: "Copie agora. Este valor não será exibido novamente…", a instrução "Use este segredo para conferir o cabeçalho X-Patrimonio-Signature de cada entrega. A assinatura é um HMAC-SHA256 do corpo da entrega com este segredo; quem mantém o sistema de destino sabe usá-la." e o segredo.
- Botões: "Copiar"/"Copiado" · "Já guardei, pode fechar" (não fecha clicando fora).
"Entregas de <nome>" (painel lateral)

- Tabela (até 100 últimas): "Quando", "Tentativa" ("1ª", "2ª"…), "Resposta" (código, tempo em ms, o erro em vermelho e o começo da resposta do destino), "Situação" ("Na fila", "Entregue", "Falhou, vai tentar de novo" — com "tenta de novo em <data>" —, "Descartada") e "Reenviar". Vazio: "Nenhuma entrega ainda."
- "Reenviar" (em entregas não entregues): recoloca na fila. Balão "Entrega recolocada na fila." Erro: "Entrega não encontrada."
- Tabela (até 100 últimas): "Quando", "Tentativa" ("1ª", "2ª"…), "Resposta" (código, tempo em ms, o erro em vermelho e o começo da resposta do destino), "Situação" ("Na fila", "Entregue", "Falhou, vai tentar de novo" — com "tenta de novo em <data>" —, "Descartada") e "Reenviar". Vazio: "Nenhuma entrega ainda."
- "Reenviar" (em entregas não entregues): recoloca na fila. Balão "Entrega recolocada na fila." Erro: "Entrega não encontrada."
Perguntas que as pessoas fazem
- O endpoint ficou "Desativado por falhas". → O destino falhou 50 vezes seguidas. Corrija o lado de lá, teste com o ping e use "Reativar".
- O destino recusa a assinatura. → O segredo mudou (rotação) e o destino ainda usa o antigo; configure lá o segredo novo.
- Posso mandar para um servidor da rede interna? → Não: só https em endereço público.
- Perdi o segredo. → Use "Rotacionar o segredo" e configure o novo no destino.
Ligações com outros módulos e telas
- Integrações › Chaves de API — acesso de sistemas externos à API (o escopo "webhooks:manage" deixa gerir webhooks pela API).
- Minha conta › Preferências de notificação — aviso "Webhook desativado por falhas".
- Telas que geram os eventos: Bens (lista), Ficha da movimentação, Campanha de inventário (detalhe), Processo de baixa (detalhe), Contabilidade › Depreciação do mês, Custódia (termos de custódia), Aprovações (caixa de alçadas), Manutenção (ordens, planos e calibrações).