> ## Documentation Index
> Fetch the complete documentation index at: https://docs.acrity.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Assinaturas de webhooks
> Como proteger webhooks de saída da Acrity com HMAC, segredos e testes.
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=` |
| `X-ACR-Event` | Tipo de evento da entrega |
| `X-ACR-Delivery` | ID único da entrega |
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.
```javascript theme={null}
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);
}
```
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.
```mermaid theme={null}
sequenceDiagram
participant A as Acrity
participant R as Seu endpoint
A->>A: Calcula HMAC-SHA256 sobre o corpo bruto com o segredo
A->>R: POST do payload com X-ACR-Signature-256
R->>R: Recalcula HMAC-SHA256 sobre o corpo bruto com o segredo
R->>R: Comparação de tempo constante com o valor do header
R-->>A: 2xx quando as assinaturas coincidem, rejeita caso contrário
```
## 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:
Configure o novo segredo no sistema que recebe o webhook.
Edite o webhook e substitua o segredo HMAC.
Confirme que o receptor valida a nova assinatura.
Acompanhe as primeiras entregas reais após a rotação.