Saltar al contenido
ComdigDocs

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.

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.
  • t va en segundos (hora Unix), no en milisegundos.
  • La firma vence si t difiere 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 ejemplo t=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#

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)
fe60a799db49b94ac6d1666f9e0bcd5c1d47a0c4d40a642fbbe3f4b9dd74cb66

Ejemplo completo#

Calcular t, firmar y enviar
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#

RespuestaCausa
401 firma_ausenteFalta el header X-Comdig-Signature.
401 firma_vencidat difiere más de 300 segundos de la hora del servidor.
401 firma_invalidaLa firma no coincide: revisa el secreto y que firmes el cuerpo exacto.