Skip to main content
Webhooks de saída enviam eventos da Acrity para sistemas externos configurados pelo workspace. Para proteger a entrega, use HTTPS, headers explícitos e uma assinatura HMAC para que o destino possa verificar a autenticidade.

​
Onde configurar

No Console, abra Webhooks no workspace. Webhooks exigem um admin de Workspace.
Formulário de novo webhook de saída onde o segredo de assinatura e os headers de entrega são configurados
Campos principais:
Mantenha Ignore SSL Verification desativado. Ativá-lo desabilita a validação do certificado TLS para o destino, o que expõe as entregas à interceptação man-in-the-middle. Use-o apenas para um teste interno de curta duração contra um host com certificado autoassinado e desative-o antes de ir para produção.

​
HMAC

Quando HMAC está habilitado, a Acrity assina o payload enviado ao destino com um segredo compartilhado. O destino deve recalcular a assinatura usando o mesmo segredo e rejeitar mensagens que não coincidirem. Boas práticas:
  • Use um segredo longo, aleatório e exclusivo por webhook.
  • Armazene o segredo no cofre do sistema receptor.
  • Valide a assinatura antes de processar o evento.
  • Rejeite requisições sem HTTPS em produção.
  • Rotacione o segredo quando houver suspeita de exposição.
Use o recurso de teste do Console antes de ativar o webhook em fluxos de produção.

​
Verificar a assinatura

Quando HMAC está habilitado, a Acrity assina cada entrega de saída e envia a assinatura em um header. Recalcule a assinatura do seu lado e compare-a com o header antes de processar o payload. Toda entrega inclui estes headers: O valor da assinatura é sha256= seguido do digest hexadecimal em minúsculas de um HMAC-SHA256 calculado sobre o corpo bruto (raw) da requisição usando o segredo do webhook. Para verificar uma entrega:
  1. Leia o corpo bruto (raw) da requisição exatamente como recebido. Não o re-serialize nem o reformate.
  2. Calcule o HMAC-SHA256 sobre o corpo bruto usando o segredo do webhook.
  3. Formate o resultado como sha256= seguido do digest hexadecimal em minúsculas.
  4. Compare seu valor com X-ACR-Signature-256 usando uma comparação de tempo constante.
  5. Rejeite a requisição se os valores não coincidirem.
Calcule o HMAC sobre os bytes brutos do corpo. Frameworks que fazem parse do JSON antes de você conseguir ler o corpo bruto alteram os bytes e quebram a verificação, então capture o corpo bruto primeiro.

​
Proteção contra replay

A Acrity não adiciona proteção contra replay baseada em timestamp às entregas de saída, e a assinatura por si só não impede que uma requisição capturada seja reenviada. Faça a deduplicação pelo ID X-ACR-Delivery: registre os IDs que você já processou e ignore repetições.

​
Verificação de entrada

Para webhooks de entrada de VCS, a Acrity verifica a assinatura do webhook do provedor antes de processar o evento, de modo que entregas que falham na validação de assinatura são rejeitadas. Isso acontece automaticamente e não requer configuração.

​
Headers secretos

Headers marcados como secretos são tratados como segredos no Console. Ao editar, deixe o valor em branco para manter o segredo salvo ou informe um novo valor para substituí-lo.

​
Testes e entregas

Use o teste de webhook para validar:
  1. Conectividade com a URL.
  2. Formato do payload.
  3. Headers obrigatórios.
  4. Validação HMAC no receptor.
  5. Códigos de resposta do destino.
A página de detalhes mostra entregas recentes e ajuda a diagnosticar falhas como URL incorreta, timeout, credencial inválida, erro de certificado ou payload rejeitado.

​
Rotação

Para rotacionar um segredo HMAC:
1

Criar novo segredo no receptor

Configure o novo segredo no sistema que recebe o webhook.
2

Atualizar o webhook na Acrity

Edite o webhook e substitua o segredo HMAC.
3

Enviar teste

Confirme que o receptor valida a nova assinatura.
4

Ativar fluxo normal

Acompanhe as primeiras entregas reais após a rotação.