Validación de la firma - Kairo Connect Docs

Kairo Shield firma cada entrega con HMAC-SHA256 del cuerpo raw (JSON compacto, UTF-8).

Encabezado de firma

X-Kairo-Signature: sha256=a1b2c3d4e5f6...

El valor incluye el prefijo sha256= seguido del digest hexadecimal.

Pasos de verificación

Lea el body sin parsear (bytes/string raw).
Calcule HMAC-SHA256(body, secret) en hexadecimal.
Compare con el valor del encabezado sin el prefijo sha256=.
Use comparación en tiempo constante (hmac.compare_digest, hash_equals, timingSafeEqual).
Si no coincide, responda 401 Unauthorized y no procese el payload.

No use el body ya parseado por su framework para calcular la firma. Cualquier cambio de espacios o orden de claves invalidará la verificación.

Ejemplo conceptual (Python)

import hmac
import hashlib

def verify_kairo_signature(raw_body: bytes, signature_header: str, secret: str) -> bool:
    expected = hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
    received = signature_header.removeprefix("sha256=")
    return hmac.compare_digest(expected, received)

Consulte Ejemplos por lenguaje para PHP, Node.js y Java.

Idempotencia

Use X-Kairo-Delivery como clave de deduplicación. Kairo Shield puede reintentar entregas fallidas.