Skip to main content

​
Webhooks

Gestiona las suscripciones a eventos de facturación (validación, rechazo, contingencia, conexión SIAT) directamente con lenguaje natural, sin tocar la API REST.

registrarWebhook

Registra una URL para recibir eventos. Soporta suscripción por tipo exacto, namespace (contingency.*) o * (todos).

listarWebhooks

Lista los endpoints de webhook registrados por el tenant.

verWebhook

Detalle de un endpoint: URL, eventos suscritos y estado.

actualizarWebhook

Cambia la URL, los eventos suscritos o activa/desactiva un endpoint.

eliminarWebhook

Elimina un endpoint de webhook registrado.

rotarSecretoWebhook

Genera un nuevo secreto de firma para un endpoint, invalidando el anterior.

listarEntregasWebhook

Historial de entregas de un endpoint: estado, intentos y código de respuesta.

reenviarEntregaWebhook

Fuerza el reenvío de una entrega puntual sin esperar el backoff automático.

​
registrarWebhook \

Registra un nuevo endpoint de webhook para recibir eventos de facturación en tiempo real.
ParámetroTipoRequeridoDescripción
urlStringSíURL https:// que recibirá las entregas
eventsArray<String>SíEventos a suscribir: *, namespace.* o tipo exacto
descriptionStringNoNota interna para identificar el endpoint
Requiere autenticación: Sí Ejemplo de uso con AI:
“Registra un webhook a https://miapp.com/hooks/cucu para invoice.validated e invoice.rejected”

​
listarWebhooks \

Lista los endpoints de webhook registrados por el tenant autenticado.
ParámetroTipoRequeridoDescripción
(ninguno)--No requiere parámetros
Requiere autenticación: Sí Ejemplo de uso con AI:
“¿Qué webhooks tengo registrados?”

​
verWebhook \

Obtiene el detalle de un endpoint de webhook: URL, eventos suscritos, estado y fecha de creación.
ParámetroTipoRequeridoDescripción
idStringSíID del endpoint de webhook
Requiere autenticación: Sí Ejemplo de uso con AI:
“Muéstrame el detalle del webhook wh_ep_a1b2c3d4”

​
actualizarWebhook \

Actualiza la URL, los eventos suscritos, o activa/desactiva un endpoint existente.
ParámetroTipoRequeridoDescripción
idStringSíID del endpoint de webhook
urlStringNoNueva URL del endpoint
eventsArray<String>NoNueva lista de eventos suscritos
activeBooleanNoActiva o pausa las entregas a este endpoint
Requiere autenticación: Sí Ejemplo de uso con AI:
“Agrega el evento contingency.opened al webhook wh_ep_a1b2c3d4”

​
eliminarWebhook \

Elimina un endpoint de webhook registrado. Las entregas ya realizadas quedan en el historial.
ParámetroTipoRequeridoDescripción
idStringSíID del endpoint de webhook
Requiere autenticación: Sí Ejemplo de uso con AI:
“Elimina el webhook wh_ep_a1b2c3d4”

​
rotarSecretoWebhook \

Genera un nuevo secreto de firma HMAC para el endpoint, invalidando el anterior de inmediato.
ParámetroTipoRequeridoDescripción
idStringSíID del endpoint de webhook
Requiere autenticación: Sí Ejemplo de uso con AI:
“Rota el secreto del webhook wh_ep_a1b2c3d4”
El secreto anterior deja de validar entregas inmediatamente. Actualiza tu receptor antes de rotar en producción.

​
listarEntregasWebhook \

Lista el historial de entregas de un endpoint: estado, cantidad de intentos y código de respuesta recibido.
ParámetroTipoRequeridoDescripción
idStringSíID del endpoint de webhook
pageintNoPágina (inicia en 0, default: 0)
sizeintNoElementos por página (default: 20)
Requiere autenticación: Sí Ejemplo de uso con AI:
“¿Cuántas entregas fallaron en el webhook wh_ep_a1b2c3d4 esta semana?”

​
reenviarEntregaWebhook \

Fuerza el reenvío de una entrega puntual, sin esperar al backoff automático del dispatcher.
ParámetroTipoRequeridoDescripción
deliveryIdStringSíID de la entrega a reenviar
Requiere autenticación: Sí Ejemplo de uso con AI:
“Reenvía la entrega de webhook que falló esta mañana”

​
Conceptos clave

Los webhooks de facturación cubren, entre otros: invoice.* (cambios de estado de factura), contingency.opened / contingency.closed / contingency.package_rejected, siat.connection_lost / siat.connection_restored, siat.token_expiring, certificate.expiring, cufd.renewal_failed y cuis.renewal_failed. Consulta el catálogo completo en Webhooks (API REST).
Cada entrega llega firmada con HMAC-SHA256 siguiendo el estándar Standard Webhooks: headers webhook-id, webhook-timestamp, webhook-signature y webhook-event. La verificación de firma es la misma que en la API REST — ver Webhooks (API REST).
Las entregas fallidas reintentan con backoff exponencial hasta 8 intentos. Al registrar o rotar un endpoint, CUCU valida que la URL sea https:// y resuelve el host para rechazar direcciones privadas o de loopback.