cucuVerificarWebhook

Description

Checks the HMAC-SHA256 signature of a CUCU webhook delivery (webhook-id, webhook-timestamp and webhook-signature headers) and the message age. Place it right after the Floogos Webhook trigger: it takes the headers and raw body by itself. The secret comes from the credential. If the signature is invalid the node errors and the workflow does not process the delivery; a delivery can arrive more than once: use event_id to deduplicate.

Part of the Bolivia Fiscal Hub as an alternative to connecting directly to SIAT: CUCU is an authorised provider handling signing, CUIS/CUFD codes and submission to the SIN. Node: “Verificar firma de webhook”.

Configuration

Field	Type	Required	Description
credentials_id	credentials	Yes	cucu credential
headers	json	No	Headers (JSON, optional) — Empty = those of the received request
raw_body	textarea	No	Raw body (optional) — Empty = the exact body of the received request. The signature is computed over the original bytes, not a rebuilt JSON
tolerance_seconds	number	No	Age tolerance (s) — 0 = do not check the date. CUCU docs do not define a tolerance
fail_on_invalid	boolean	No	Error if the signature is invalid
output_key	text	No	Output key — The result is added to data[key] keeping the rest of the data

Credentials

This module requires a credential of type cucu with the fields:

API key: starts with sk_test_ (sandbox) or sk_live_ (production); the environment is inferred from the prefix
Environment: automatic, testing or production (if it contradicts the key, nothing is sent)
Default point of sale (UUID): used when the node does not specify one
Company ID (UUID): for branches and certificate status
Webhook secret (whsec_…): to verify event signatures

Output

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

The output is stored under the configured key (output_key, default cucu) and the rest of data is kept. On error: error.message, error.type and, where applicable, status, code and siat_code.

Usage Example

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

Notes

Verifies the standard signature (Standard Webhooks): webhook-id, webhook-timestamp and webhook-signature (HMAC-SHA256 of id.timestamp.body). 5-minute tolerance. Makes no call to CUCU.
Reads the headers and raw body from the trigger. If the raw body is unavailable it is rebuilt from the JSON and a warning is added: it may fail due to formatting differences.
With “Fail if invalid” (default) a bad signature stops the workflow.

cucuWebhooks - Gestionar webhooks