Webhooks

Notificaciones de cambios de factura, contingencia y conexión con el SIAT, en lugar de hacer polling a GET /api/v3/invoices/{id}/status.

Registrar un endpoint

POST /api/v3/webhooks/endpoints

Parametro	Ubicacion	Tipo	Req	Descripcion
`X-API-Key`	Header	string	Si	Tu API Key
`url`	Body	string	Si	URL `https://` que recibirá las entregas. Sin credenciales embebidas (`https://usuario:clave@...` se rechaza) y con un host que resuelva a una IP pública — ver Seguridad
`events`	Body	array<string>	Si	Eventos a suscribir. Acepta ``, `namespace.` (ej. `contingency.*`) o el tipo exacto
`description`	Body	string	No	Nota interna para identificar el endpoint

curl -X POST https://sandbox.cucu.bo/api/v3/webhooks/endpoints \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "url": "https://tuservidor.com/webhooks/cucu",
    "events": ["invoice.validated", "invoice.rejected", "contingency.*"],
    "description": "Sincronizacion con ERP"
  }'

const response = await fetch('https://sandbox.cucu.bo/api/v3/webhooks/endpoints', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': process.env.CUCU_API_KEY
  },
  body: JSON.stringify({
    url: 'https://tuservidor.com/webhooks/cucu',
    events: ['invoice.validated', 'invoice.rejected', 'contingency.*'],
    description: 'Sincronizacion con ERP'
  })
});

import requests

response = requests.post(
    'https://sandbox.cucu.bo/api/v3/webhooks/endpoints',
    headers={'X-API-Key': 'YOUR_API_KEY'},
    json={
        'url': 'https://tuservidor.com/webhooks/cucu',
        'events': ['invoice.validated', 'invoice.rejected', 'contingency.*'],
        'description': 'Sincronizacion con ERP'
    }
)

Respuesta (201):

{
  "success": true,
  "data": {
    "id": "wh_ep_a1b2c3d4",
    "url": "https://tuservidor.com/webhooks/cucu",
    "events": ["invoice.validated", "invoice.rejected", "contingency.*"],
    "secret": "whsec_...",
    "active": true,
    "createdAt": "2026-07-01T10:00:00"
  }
}

El secret solo se muestra completo aquí y al rotarlo: guárdalo para verificar las firmas.

Errores al registrar o actualizar

La URL se valida al crear y al cambiarla con PUT; si falla, 400 con error.code = BAD_REQUEST y uno de estos message:

`message`	Causa
`La URL del webhook debe ser https`	Esquema distinto de `https://`
`La URL del webhook no tiene host`	URL sin host
`La URL del webhook no admite credenciales embebidas`	`usuario:clave@` en la URL
`URL inválida: <url>`	No se pudo parsear
`No se pudo resolver el host de la URL: <host>`	El DNS no resuelve el host
`La URL apunta a una dirección interna/privada no permitida`	Alguna de las IP a las que resuelve el host está en un rango bloqueado (ver Seguridad)
`Límite de endpoints de webhook alcanzado (20). Eliminá o deshabilitá alguno antes de crear otro.`	Ya hay 20 endpoints activos

400

{
  "success": false,
  "message": "La URL del webhook no admite credenciales embebidas",
  "error": {
    "code": "BAD_REQUEST"
  },
  "timestamp": "2026-10-28T12:00:00"
}

Gestionar endpoints

Accion	Endpoint
Listar endpoints	`GET /api/v3/webhooks/endpoints`
Ver un endpoint	`GET /api/v3/webhooks/endpoints/{id}`
Actualizar (url, events, activo)	`PUT /api/v3/webhooks/endpoints/{id}`
Eliminar	`DELETE /api/v3/webhooks/endpoints/{id}`
Rotar secreto	`POST /api/v3/webhooks/endpoints/{id}/rotate-secret`

Todas requieren el header X-API-Key.

Catálogo de eventos

Evento	Descripción
`invoice.*`	Un evento por cada cambio de estado de una factura (validada, rechazada, anulada), reflejando los mismos estados documentados en el ciclo de vida de la factura
`contingency.opened`	Se activó contingencia offline en un punto de venta
`contingency.closed`	La contingencia finalizó y las facturas se sincronizaron con el SIAT
`contingency.package_rejected`	El SIAT rechazó el paquete de facturas enviado al reconectar
`siat.connection_lost`	cucu detectó que el SIAT dejó de responder
`siat.connection_restored`	La conexión con el SIAT se restableció
`siat.token_expiring`	El token de sesión SIAT está por expirar
`certificate.expiring`	El certificado digital del tenant está por vencer
`cufd.renewal_failed`	Falló la renovación automática del CUFD
`cuis.renewal_failed`	Falló la renovación automática del CUIS

Suscripción con *, un namespace (contingency.*, siat.*) o un tipo exacto de este catálogo.

Seguridad

HTTPS obligatorio, sin credenciales embebidas (usuario:clave@).
Anti-SSRF. El host se resuelve al registrar (400 si cae en un rango bloqueado) y otra vez en cada entrega; si ahora resuelve a una IP interna no se entrega (lastError = "Destino del webhook no permitido").
Rangos bloqueados. IPv4: loopback (127.0.0.0/8), privadas (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16), CGNAT (100.64.0.0/10), link-local y metadata (169.254.0.0/16), 0.0.0.0/8, 192.0.0.0/24, 198.18.0.0/15, multicast (224.0.0.0/4) y 240.0.0.0/4. IPv6: ::1, ::, link-local (fe80::/10), site-local, ULA (fc00::/7), multicast (ff00::/8), 100::/64 y Teredo (2001::/32). Una IPv4 embebida en IPv6 (::ffff:a.b.c.d, NAT64 64:ff9b::/96, 6to4 2002::/16) se evalúa por la IPv4 que contiene.
Sin redirecciones. Un 301/302 cuenta como fallo (HTTP 301).
Firma HMAC-SHA256 según Standard Webhooks.

Headers en cada entrega

Header	Descripción
`webhook-id`	UUID único de esta entrega. Úsalo para deduplicar en tu receptor.
`webhook-timestamp`	UNIX timestamp del momento del envío.
`webhook-signature`	Firma de autenticidad. Formato: `v1,<base64(HMAC-SHA256)>`.
`webhook-event`	Tipo de evento entregado (ej. `invoice.validated`).

Verificación de firma

mensaje_a_firmar = "{webhook-id}.{webhook-timestamp}.{raw_body_bytes}"
firma_esperada   = base64( HMAC-SHA256(mensaje_a_firmar, tu_secret) )

Compara firma_esperada con webhook-signature (sin el prefijo v1,) en tiempo constante.

Payload de ejemplo

{
  "type": "invoice.emitted",
  "id": "evt_5f0c2a1e-7d3b-4c8e-9a61-2b7e4f9d0c13",
  "timestamp": "2026-10-23T20:35:11.802+0000",
  "api_version": "2026-06-01",
  "company_nit": "591164023",
  "data": {
    "invoice_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "invoice_number": 192,
    "cuf": "2872F7294502332E637FABFBC3654EA82202AD48E0969F14EBEB8AF74",
    "emission_date": "2026-10-23T16:35:09",
    "client_nit": "12345678",
    "client_name": "Cucu",
    "client_email": null,
    "amount_subtotal": 100.00,
    "amount_discount": 0.00,
    "amount_total": 100.00,
    "siat_state": "VALIDATED",
    "siat_code_state": 908,
    "qr_code": "https://siat.impuestos.gob.bo/consulta/QR?nit=...",
    "documents": {
      "a4": "https://api.cucu.bo/api/v3/invoices/a1b2c3d4-e5f6-7890-abcd-ef1234567890/documents/a4",
      "ticket": "https://api.cucu.bo/api/v3/invoices/a1b2c3d4-e5f6-7890-abcd-ef1234567890/documents/ticket",
      "ticketsiat": "https://api.cucu.bo/api/v3/invoices/a1b2c3d4-e5f6-7890-abcd-ef1234567890/documents/ticketsiat",
      "xml": "https://api.cucu.bo/api/v3/invoices/a1b2c3d4-e5f6-7890-abcd-ef1234567890/documents/xml",
      "zip": "https://api.cucu.bo/api/v3/invoices/a1b2c3d4-e5f6-7890-abcd-ef1234567890/documents/zip"
    },
    "cancellation_reason": null,
    "idempotency_key": "odoo:3f9c...:1:pos:00012-003-0004"
  }
}

SIAT v3 (IVA transparente) agrega siat_version, price_basis, amount_net, amount_iva, amount_requested y amount_difference (nulos en v2). Ver priceBasis. documents (eventos invoice.*): URLs de los endpoints autenticados (con tu API Key), solo en facturas con documento. idempotency_key: el Idempotency-Key de la emisión (null sin él).

invoice.emitted puede llegar antes que el email. No lo tomes como confirmación de envío del correo.

Política de reintentos

Responde 2xx en el timeout (5 s para conectar, 10 s para responder). Si no, se reintenta con backoff exponencial hasta 8 intentos. Solo cuenta el código HTTP.

El mismo evento puede llegar más de una vez: deduplica con webhook-id.

Auditoría y reenvío manual

Accion	Endpoint
Listar entregas de un endpoint	`GET /api/v3/webhooks/endpoints/{id}/deliveries`
Forzar el reenvío de una entrega	`POST /api/v3/webhooks/deliveries/{deliveryId}/redeliver`

Cada entrega trae status (PENDING, DELIVERED, FAILED, DEAD), attempts, maxAttempts, lastStatusCode y lastError:

`lastError`	Significado
`HTTP <código>`	Tu endpoint respondió, pero no `2xx` (ej. `HTTP 500`, `HTTP 302`)
`No se pudo conectar con el endpoint o no respondió a tiempo`	Cualquier fallo de red una vez resuelto el destino: conexión rechazada, timeout o TLS inválido. No se distingue cuál
`Destino del webhook no permitido`	Al momento de entregar, la URL no pasó la política: el host resolvió a una IP de un rango bloqueado (ver Seguridad) o directamente no resuelve. Se reintenta igual; corrige el DNS o la URL
`Endpoint inactivo o eliminado`	El endpoint se desactivó o eliminó antes de que la entrega saliera; la entrega pasa a `DEAD` sin reintentos

Empezar

Planes

Referencia

Próximos cambios

Endpoints

Documentos Sector

Utilidades y Soporte

Webhooks

Webhooks

Registrar un endpoint

Errores al registrar o actualizar

Gestionar endpoints

Catálogo de eventos

Seguridad

Headers en cada entrega

Verificación de firma

Payload de ejemplo

Política de reintentos

Auditoría y reenvío manual