Webhooks entrantes
Verificar la firma
Cómo calcular el header X-Comdig-Signature (HMAC-SHA256) de los webhooks entrantes de Comdig, con ejemplos en Node, Python y shell.
En esta página
Formato del header#
Header
X-Comdig-Signature: t=<unix_seconds>,v1=<firma>Donde firma = hex(HMAC-SHA256(secreto, t + "." + cuerpo_crudo)).
Reglas#
- Firma exactamente los bytes del cuerpo que envías. No vuelvas a serializar el JSON después de firmarlo.
tva en segundos (hora Unix), no en milisegundos.- La firma vence si
tdifiere más de 300 segundos de la hora del servidor (firma_vencida). Mantén el reloj de tu servidor sincronizado. - Puedes enviar varios
v1=en el mismo header, por ejemplot=1700000000,v1=<firma_nueva>,v1=<firma_anterior>. Sirve para que tu sistema firme con ambos secretos mientras actualizas su configuración. - Al generar un Nuevo secreto en Comdig, el anterior deja de validar de inmediato: después de rotar, solo el nuevo es válido. Genera el nuevo secreto, actualiza el emisor enseguida y verifica en el Historial de la conexión.
- Envía
Content-Type: application/json.
Calcular la firma#
import crypto from "node:crypto";
function firmar(secret, t, body) {
return crypto.createHmac("sha256", secret).update(`${t}.${body}`).digest("hex");
}Vector de prueba#
Con el secreto whsec_test, t = 1700000000 y el cuerpo {"event_id":"1"}, los tres ejemplos dan:
Firma (hex)
fe60a799db49b94ac6d1666f9e0bcd5c1d47a0c4d40a642fbbe3f4b9dd74cb66Ejemplo completo#
secret="$COMDIG_WEBHOOK_SECRET"
body='{"event_id":"fac-1001","event_type":"factura_emitida","cliente":{"nombre":"Ana Gómez","telefono":"+573001234567"},"factura":{"numero":"FV-1001","total":"120.000"}}'
t=$(date +%s)
firma=$(printf '%s.%s' "$t" "$body" | openssl dgst -sha256 -hmac "$secret" -hex | awk '{print $NF}')
curl -X POST "https://api.comdig.co/v1/inbound-webhook?c=$COMDIG_CONNECTION_ID" \
-H "Content-Type: application/json" \
-H "X-Comdig-Signature: t=$t,v1=$firma" \
--data-binary "$body"Errores de firma#
| Respuesta | Causa |
|---|---|
401 firma_ausente | Falta el header X-Comdig-Signature. |
401 firma_vencida | t difiere más de 300 segundos de la hora del servidor. |
401 firma_invalida | La firma no coincide: revisa el secreto y que firmes el cuerpo exacto. |