Console > Webhooks para criar, testar, ativar, desativar, editar e acompanhar entregas.
Quando usar
Use webhooks quando:- um sistema externo precisa reagir a eventos da Acrity;
- uma automação interna deve receber notificações;
- você precisa alimentar observabilidade, auditoria ou dashboards;
- integrações via API polling não são desejáveis.
Console > API Keys quando o sistema externo precisar consultar dados ativamente.
Quem pode acessar
Admins de workspace normalmente gerenciam webhooks.Campos principais
| Campo | Para que serve |
|---|---|
| Nome | Identifica o webhook no Console. |
| URL | Endpoint externo que receberá o evento. |
| Método | Método HTTP usado na entrega. |
| Content type | Formato do corpo enviado. |
| Eventos | Tipos de evento que disparam o webhook. |
| Headers | Cabeçalhos adicionais enviados na requisição. |
| Headers secretos | Cabeçalhos cujo valor deve ser protegido e não exibido novamente. |
| HMAC | Assinatura para permitir verificação de origem pelo destinatário. |
| Body template | Modelo opcional para personalizar o payload enviado. |
| Ignorar verificação SSL | Opção excepcional para ambientes controlados. Evite em produção. |
Criar um webhook
Configurar segurança
Adicione headers necessários e habilite HMAC quando o destinatário puder validar assinatura.
Headers e segredos
Use headers para enviar tokens, identificadores ou informações exigidas pelo destino. Boas práticas:- marque como secreto qualquer header que contenha token ou segredo;
- não coloque segredos no nome do webhook;
- prefira rotação de tokens no sistema destinatário;
- remova headers que não são usados;
- documente internamente o dono do endpoint.
HMAC
HMAC permite que o sistema destinatário valide que o payload veio da Acrity e não foi alterado em trânsito. Use HMAC sempre que o destino suportar verificação de assinatura. Ao habilitar:- Gere ou informe um segredo forte.
- Configure o mesmo segredo no sistema destinatário.
- Teste uma entrega.
- Rejeite payloads sem assinatura válida no destino.
Body template
O body template personaliza o corpo enviado. Use quando o destino espera um formato específico. Recomendações:- comece com payload simples;
- valide com a prévia antes de salvar;
- evite incluir dados sensíveis desnecessários;
- mantenha compatibilidade com o sistema destinatário;
- versione mudanças importantes do lado receptor.
Testar entrega
Antes de ativar um webhook crítico:- use a ação de teste da tela;
- confirme status de resposta do destino;
- verifique logs do sistema receptor;
- valide assinatura HMAC quando habilitada;
- revise headers e content type;
- confirme que o payload esperado chegou.
Histórico de entregas
O detalhe do webhook pode exibir histórico de entregas. Use esse histórico para investigar:- sucesso ou falha de envio;
- status retornado pelo destino;
- tempo de resposta;
- payload de teste ou entrega quando exibido pela tela;
- erros de conexão, TLS ou validação.
Ativar e desativar
Desative um webhook quando:- o destino está em manutenção;
- o endpoint foi substituído;
- há suspeita de segredo exposto;
- a integração está gerando ruído;
- você precisa pausar entregas temporariamente.
Problemas comuns
| Sintoma | O que verificar |
|---|---|
| Webhook não salva | Confira URL, método, content type, eventos e validações da tela. |
| Teste retorna erro | Verifique se o endpoint está acessível publicamente ou pela rede esperada. |
| Destino rejeita payload | Confira content type, template e schema esperado pelo receptor. |
| Assinatura inválida | Verifique segredo HMAC nos dois lados e se o receptor usa o payload bruto correto. |
| Erro TLS | Corrija certificado do destino. Evite ignorar SSL em produção. |
Segurança
Webhooks podem enviar dados operacionais para fora da Acrity. Configure apenas destinos confiáveis e revise periodicamente quais eventos estão ativos. Detalhes sobre tratamento de dados ficam emSegurança > Tratamento de dados.