> ## 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.
# Firmas de webhooks
> Cómo proteger los webhooks salientes de Acrity con HMAC, secretos y pruebas.
Los webhooks salientes envían eventos de Acrity a sistemas externos configurados por el workspace. Para proteger la entrega, usa HTTPS, headers explícitos y una firma HMAC para que el destino pueda verificar la autenticidad.
## Dónde configurar
En la Consola, abre **Webhooks** en el workspace. Los webhooks requieren un administrador de workspace (los administradores de plataforma también tienen acceso).
Campos principales:
| Campo | Finalidad |
| ----------------------- | ------------------------------------------------------------------------ |
| Nombre | Identifica el destino en la Consola y en el registro de auditoría |
| URL | Endpoint HTTPS que recibe el evento |
| Método | Método HTTP para la entrega (`POST`) |
| Content type | Formato aceptado por el destino |
| Eventos | Qué eventos disparan la entrega |
| Headers | Encabezados fijos, incluidos los tokens del destino cuando sea necesario |
| HMAC | Firma que el destino usa para verificar la autenticidad |
| Body template | Payload personalizado cuando el destino requiere un formato específico |
| Ignore SSL Verification | Omite la validación del certificado TLS para el endpoint de destino |
Deja **Ignore SSL Verification** desactivado. Activarlo deshabilita la validación del certificado TLS para el destino, lo que expone las entregas a interceptación de tipo man-in-the-middle. Úsalo solo para una prueba interna de corta duración contra un host con un certificado autofirmado, y desactívalo antes de producción.
## HMAC
Cuando HMAC está habilitado, Acrity firma el payload enviado al destino con un secreto compartido. El destino debe recalcular la firma con el mismo secreto y rechazar los mensajes que no coincidan.
Buenas prácticas:
* Usa un secreto largo, aleatorio y único por webhook.
* Almacena el secreto en el cofre del sistema receptor.
* Valida la firma antes de procesar el evento.
* Rechaza las solicitudes sin HTTPS en producción.
* Rota el secreto cuando se sospeche de una exposición.
Usa la función de prueba de la Consola antes de activar el webhook en flujos de producción.
## Verificar la firma
Cuando HMAC está habilitado, Acrity firma cada entrega saliente y envía la firma en un header. Vuelve a calcular la firma de tu lado y compárala con el header antes de procesar el payload.
Cada entrega incluye estos headers:
| Header | Descripción |
| --------------------- | -------------------------------------------- |
| `X-ACR-Signature-256` | Firma en el formato `sha256=` |
| `X-ACR-Event` | Tipo de evento de la entrega |
| `X-ACR-Delivery` | ID único de la entrega |
El valor de la firma es `sha256=` seguido del digest hexadecimal en minúsculas de un HMAC-SHA256 calculado sobre el cuerpo sin procesar (raw) de la solicitud usando el secreto del webhook.
Para verificar una entrega:
1. Lee el cuerpo sin procesar (raw) de la solicitud exactamente como se recibió. No lo vuelvas a serializar ni a reformatear.
2. Calcula HMAC-SHA256 sobre el cuerpo sin procesar usando el secreto del webhook.
3. Formatea el resultado como `sha256=` seguido del digest hexadecimal en minúsculas.
4. Compara tu valor con `X-ACR-Signature-256` usando una comparación de tiempo constante.
5. Rechaza la solicitud si los valores no coinciden.
```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);
}
```
Calcula el HMAC sobre los bytes sin procesar del cuerpo. Los frameworks que parsean el JSON antes de que puedas leer el cuerpo sin procesar cambian los bytes y rompen la verificación, así que captura primero el cuerpo sin procesar.
```mermaid theme={null}
sequenceDiagram
participant A as Acrity
participant R as Tu endpoint
A->>A: Calcula HMAC-SHA256 sobre el cuerpo sin procesar con el secreto
A->>R: POST del payload con X-ACR-Signature-256
R->>R: Recalcula HMAC-SHA256 sobre el cuerpo sin procesar con el secreto
R->>R: Comparación de tiempo constante con el valor del header
R-->>A: 2xx cuando las firmas coinciden, rechazar en caso contrario
```
## Protección contra reenvío (replay)
Acrity no agrega protección contra reenvío basada en marca de tiempo a las entregas salientes, y la firma por sí sola no evita que una solicitud capturada sea reenviada. Deduplica por el ID `X-ACR-Delivery`: registra los IDs que ya has procesado e ignora las repeticiones.
## Verificación entrante
Para los webhooks entrantes de VCS, Acrity verifica la firma del webhook del proveedor antes de procesar el evento, por lo que las entregas que no superan la validación de firma se rechazan. Esto ocurre automáticamente y no requiere configuración.
## Headers secretos
Los headers marcados como secretos se tratan como secretos en la Consola. Al editar, deja el valor en blanco para mantener el secreto guardado, o introduce un nuevo valor para reemplazarlo.
## Pruebas y entregas
Usa la prueba del webhook para validar:
1. Conectividad con la URL.
2. Formato del payload.
3. Headers obligatorios.
4. Validación de HMAC en el receptor.
5. Códigos de respuesta del destino.
La página de detalles muestra las entregas recientes y ayuda a diagnosticar fallas como una URL incorrecta, timeout, credencial inválida, error de certificado o payload rechazado.
## Rotación
Para rotar un secreto HMAC:
Configura el nuevo secreto en el sistema que recibe el webhook.
Edita el webhook y reemplaza el secreto HMAC.
Confirma que el receptor valide la nueva firma.
Da seguimiento a las primeras entregas reales después de la rotación.