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.
Campos principais:
| Campo | Finalidade |
|---|
| Nome | Identifica o destino no Console e na trilha de auditoria |
| URL | Endpoint HTTPS que recebe o evento |
| Método | Método HTTP para entrega (POST) |
| Content type | Formato aceito pelo destino |
| Eventos | Quais eventos disparam a entrega |
| Headers | Cabeçalhos fixos, incluindo tokens do destino quando necessário |
| HMAC | Assinatura que o destino usa para verificar a autenticidade |
| Body template | Payload customizado quando o destino exige um formato específico |
| Ignore SSL Verification | Ignora a validação do certificado TLS para o endpoint de destino |
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:
| Header | Descrição |
|---|
X-ACR-Signature-256 | Assinatura no formato sha256=<lowercase hex> |
X-ACR-Event | Tipo de evento da entrega |
X-ACR-Delivery | ID único da entrega |
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:
- Leia o corpo bruto (raw) da requisição exatamente como recebido. Não o re-serialize nem o reformate.
- Calcule o HMAC-SHA256 sobre o corpo bruto usando o segredo do webhook.
- Formate o resultado como
sha256= seguido do digest hexadecimal em minúsculas.
- Compare seu valor com
X-ACR-Signature-256 usando uma comparação de tempo constante.
- Rejeite a requisição se os valores não coincidirem.
import crypto from "node:crypto";
function verifySignature(rawBody, signatureHeader, secret) {
const expected =
"sha256=" +
crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
const a = Buffer.from(expected);
const b = Buffer.from(signatureHeader || "");
// Lengths must match for timingSafeEqual; the length check itself is not secret.
return a.length === b.length && crypto.timingSafeEqual(a, b);
}
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 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:
- Conectividade com a URL.
- Formato do payload.
- Headers obrigatórios.
- Validação HMAC no receptor.
- 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:
Criar novo segredo no receptor
Configure o novo segredo no sistema que recebe o webhook.
Atualizar o webhook na Acrity
Edite o webhook e substitua o segredo HMAC.
Enviar teste
Confirme que o receptor valida a nova assinatura.
Ativar fluxo normal
Acompanhe as primeiras entregas reais após a rotação.
