Rotación de Webhook Secrets

El secret de webhook es el secret compartido que DVS usa para firmar con HMAC cada entrega de webhook. Rotarlo periódicamente (o de inmediato tras cualquier sospecha de exposición) es una buena práctica.

Cuándo rotar

• Rotación de rutina: cada 12 meses por política de OSIGU.
• Rotación inmediata: si se sospecha que el secret quedó expuesto (commiteado a un repo público, filtrado en logs, salida de personal con acceso).
• Iniciada por OSIGU: si el monitoreo de OSIGU detecta patrones sospechosos de firma o entrega.

Cómo funciona la rotación

1. 1Solicitar la rotación

   Enviar un correo a support@osigu.com con el asunto Rotación de webhook secret — <tenant slug>. Incluir la razón y el ID del endpoint de webhook (si se tiene).

2. 2OSIGU emite un nuevo secret

   El operador de OSIGU ejecuta el endpoint admin y envía el nuevo secret en texto plano vía un canal seguro (link a un vault de 1Password, correo cifrado, entrega en persona — nunca correo plano).

3. 3Periodo de gracia de 24 horas

   Durante 24 horas tras la rotación, DVS continúa firmando para que la verificación de signature acepte tanto el secret nuevo como el anterior. Esto evita mensajes perdidos por webhooks en vuelo. Pasadas 24 horas, solo el secret nuevo es válido.

4. 4Actualizar el receptor

   Actualizar la variable de entorno / store de secrets con el nuevo valor. Se recomienda fuertemente soportar ambos secrets simultáneamente durante el periodo de gracia.

Patrón de receptor: soportar dos secrets durante la rotación

Este patrón permite cambiar de secret sin perder webhooks. Agregar el secret anterior como fallback por 24 horas y luego removerlo.

Python

SECRETS = [
    os.environ["DVS_WEBHOOK_SECRET_CURRENT"],
    os.environ.get("DVS_WEBHOOK_SECRET_PREVIOUS"),  # opcional, solo durante la ventana de gracia
]

def verify_with_any(raw_body, signature_header, timestamp_header):
    for secret in SECRETS:
        if secret and verify_dvs_signature(raw_body, signature_header, timestamp_header, secret):
            return True
    return False

Node.js

const SECRETS = [
  process.env.DVS_WEBHOOK_SECRET_CURRENT,
  process.env.DVS_WEBHOOK_SECRET_PREVIOUS, // opcional durante la ventana de gracia
].filter(Boolean);

function verifyWithAny(rawBody, signatureHeader, timestampHeader) {
  return SECRETS.some((secret) =>
    verifyDvsSignature(rawBody, signatureHeader, timestampHeader, secret),
  );
}

Pasadas 24 horas, remover DVS_WEBHOOK_SECRET_PREVIOUS del entorno.

Qué hace DVS durante la rotación

• DVS firma todos los nuevos webhooks con el secret nuevo de inmediato.
• El hash del secret anterior se retiene 24h y es aceptado por el receptor (siempre que se implemente el fallback descrito arriba).
• Pasadas 24 horas, el secret anterior se purga del almacenamiento de DVS.

Qué NO hace la rotación

• No cambia la URL del webhook.
• No cambia el ID del endpoint.
• No pausa la entrega de webhooks — los eventos siguen fluyendo.

¿Se perdió el secret?

Si ya no se tiene el secret (p. ej., la única persona con acceso dejó la empresa), no es posible recuperarlo desde DVS — los secrets están hasheados con bcrypt del lado de DVS y nunca se almacenan en texto plano. Solicitar una rotación; OSIGU emite uno nuevo.