Saltar al contenido principal
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).
Formulario de nuevo webhook saliente donde se configuran el secreto de firma y los headers de entrega
Campos principales:
CampoFinalidad
NombreIdentifica el destino en la Consola y en el registro de auditoría
URLEndpoint HTTPS que recibe el evento
MétodoMétodo HTTP para la entrega (POST)
Content typeFormato aceptado por el destino
EventosQué eventos disparan la entrega
HeadersEncabezados fijos, incluidos los tokens del destino cuando sea necesario
HMACFirma que el destino usa para verificar la autenticidad
Body templatePayload personalizado cuando el destino requiere un formato específico
Ignore SSL VerificationOmite 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:
HeaderDescripción
X-ACR-Signature-256Firma en el formato sha256=<lowercase hex>
X-ACR-EventTipo de evento de la entrega
X-ACR-DeliveryID ú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.
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.

​
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:
1

Crear un nuevo secreto en el receptor

Configura el nuevo secreto en el sistema que recibe el webhook.
2

Actualizar el webhook en Acrity

Edita el webhook y reemplaza el secreto HMAC.
3

Enviar prueba

Confirma que el receptor valide la nueva firma.
4

Activar el flujo normal

Da seguimiento a las primeras entregas reales después de la rotación.