cucuVerificarWebhook

Descripción

Comprueba la firma HMAC-SHA256 de una entrega de webhook de CUCU (cabeceras webhook-id, webhook-timestamp y webhook-signature) y la antigüedad del mensaje. Colócalo justo después del disparador Webhook de Floogos: toma solas las cabeceras y el cuerpo crudo. El secreto sale de la credencial. Si la firma no es válida, el nodo da error y el workflow no procesa la entrega; la entrega puede llegar más de una vez: usa event_id para deduplicar.

Forma parte del Hub Fiscal de Bolivia como alternativa a la conexión directa con el SIAT: CUCU es un proveedor autorizado que se ocupa de la firma, los códigos CUIS/CUFD y el envío al SIN. Nodo: «Verificar firma de webhook».

Configuración

Campo	Tipo	Requerido	Descripción
credentials_id	credentials	Sí	Credencial cucu
headers	json	No	Cabeceras (JSON, opcional) — Vacío = las de la petición recibida
raw_body	textarea	No	Cuerpo crudo (opcional) — Vacío = el cuerpo exacto de la petición recibida. La firma se calcula sobre los bytes originales, no sobre un JSON reconstruido
tolerance_seconds	number	No	Tolerancia de antigüedad (s) — 0 = no comprobar la fecha. La documentación de CUCU no fija una tolerancia
fail_on_invalid	boolean	No	Dar error si la firma no es válida
output_key	text	No	Clave de salida — El resultado se añade a data[clave] sin perder el resto de datos

Credenciales

Este módulo requiere una credencial de tipo cucu con los campos:

• API key: empieza por sk_test_ (sandbox) o sk_live_ (producción); el entorno se deduce del prefijo
• Entorno: automático, pruebas o producción (si contradice la clave, no se envía nada)
• Punto de venta por defecto (UUID): se usa si el nodo no indica uno
• ID de empresa (UUID): para sucursales y estado del certificado
• Secreto de webhooks (whsec_…): para verificar la firma de los eventos

Salida

{
  "valid": true,
  "event_type": "invoice.validated",
  "event_id": "msg_9",
  "event": {
    "type": "invoice.validated",
    "data": {
      "amount_total": 100
    }
  },
  "warnings": []
}

La salida se guarda en la clave configurada (output_key, por defecto cucu) y se conserva el resto de data. En error: error.message, error.type y, si aplica, status, code y siat_code.

Ejemplo de Uso

{
  "credentials_id": "cred-cucu",
  "fail_on_invalid": true
}

Notas

• Verifica la firma estándar (Standard Webhooks): webhook-id, webhook-timestamp y webhook-signature (HMAC-SHA256 de id.timestamp.cuerpo). Tolerancia de 5 minutos. No hace ninguna llamada a CUCU.
• Lee las cabeceras y el cuerpo crudo del disparador. Si el cuerpo crudo no está disponible se reconstruye desde el JSON y se avisa: puede fallar por diferencias de formato.
• Con «Fallar si no es válido» (por defecto) una firma incorrecta corta el workflow.

Nodos Relacionados

• cucuWebhooks - Gestionar webhooks