> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cucu.bo/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

> Las 8 herramientas MCP para gestionar webhooks de facturación: registro, consulta, rotación de secreto y auditoría de entregas.

## 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.

<CardGroup cols={2}>
  <Card title="registrarWebhook" icon="plus" href="#registrarwebhook">
    Registra una URL para recibir eventos. Soporta suscripción por
    tipo exacto, namespace (`contingency.*`) o `*` (todos).
  </Card>

  <Card title="listarWebhooks" icon="list" href="#listarwebhooks">
    Lista los endpoints de webhook registrados por el tenant.
  </Card>

  <Card title="verWebhook" icon="magnifying-glass" href="#verwebhook">
    Detalle de un endpoint: URL, eventos suscritos y estado.
  </Card>

  <Card title="actualizarWebhook" icon="pen" href="#actualizarwebhook">
    Cambia la URL, los eventos suscritos o activa/desactiva un endpoint.
  </Card>

  <Card title="eliminarWebhook" icon="trash" href="#eliminarwebhook">
    Elimina un endpoint de webhook registrado.
  </Card>

  <Card title="rotarSecretoWebhook" icon="key" href="#rotarsecretowebhook">
    Genera un nuevo secreto de firma para un endpoint, invalidando el anterior.
  </Card>

  <Card title="listarEntregasWebhook" icon="clock-rotate-left" href="#listarentregaswebhook">
    Historial de entregas de un endpoint: estado, intentos y código de respuesta.
  </Card>

  <Card title="reenviarEntregaWebhook" icon="rotate-right" href="#reenviarentregawebhook">
    Fuerza el reenvío de una entrega puntual sin esperar el backoff automático.
  </Card>
</CardGroup>

***

<h2 id="registrarwebhook\">
  registrarWebhook \\
</h2>

Registra un nuevo endpoint de webhook para recibir eventos de facturación en tiempo real.

| Parámetro     | Tipo           | Requerido | Descripción                                           |
| ------------- | -------------- | --------- | ----------------------------------------------------- |
| `url`         | String         | Sí        | URL `https://` que recibirá las entregas              |
| `events`      | Array\<String> | Sí        | Eventos a suscribir: `*`, `namespace.*` o tipo exacto |
| `description` | String         | No        | Nota interna para identificar el endpoint             |

**Requiere autenticación:** Sí

**Ejemplo de uso con AI:**

> "Registra un webhook a [https://miapp.com/hooks/cucu](https://miapp.com/hooks/cucu) para invoice.validated e invoice.rejected"

***

<h2 id="listarwebhooks\">
  listarWebhooks \\
</h2>

Lista los endpoints de webhook registrados por el tenant autenticado.

| Parámetro   | Tipo | Requerido | Descripción            |
| ----------- | ---- | --------- | ---------------------- |
| *(ninguno)* | -    | -         | No requiere parámetros |

**Requiere autenticación:** Sí

**Ejemplo de uso con AI:**

> "¿Qué webhooks tengo registrados?"

***

<h2 id="verwebhook\">
  verWebhook \\
</h2>

Obtiene el detalle de un endpoint de webhook: URL, eventos suscritos, estado y fecha de creación.

| Parámetro | Tipo   | Requerido | Descripción                |
| --------- | ------ | --------- | -------------------------- |
| `id`      | String | Sí        | ID del endpoint de webhook |

**Requiere autenticación:** Sí

**Ejemplo de uso con AI:**

> "Muéstrame el detalle del webhook wh\_ep\_a1b2c3d4"

***

<h2 id="actualizarwebhook\">
  actualizarWebhook \\
</h2>

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

| Parámetro | Tipo           | Requerido | Descripción                                 |
| --------- | -------------- | --------- | ------------------------------------------- |
| `id`      | String         | Sí        | ID del endpoint de webhook                  |
| `url`     | String         | No        | Nueva URL del endpoint                      |
| `events`  | Array\<String> | No        | Nueva lista de eventos suscritos            |
| `active`  | Boolean        | No        | Activa 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"

***

<h2 id="eliminarwebhook\">
  eliminarWebhook \\
</h2>

Elimina un endpoint de webhook registrado. Las entregas ya realizadas quedan en el historial.

| Parámetro | Tipo   | Requerido | Descripción                |
| --------- | ------ | --------- | -------------------------- |
| `id`      | String | Sí        | ID del endpoint de webhook |

**Requiere autenticación:** Sí

**Ejemplo de uso con AI:**

> "Elimina el webhook wh\_ep\_a1b2c3d4"

***

<h2 id="rotarsecretowebhook\">
  rotarSecretoWebhook \\
</h2>

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

| Parámetro | Tipo   | Requerido | Descripción                |
| --------- | ------ | --------- | -------------------------- |
| `id`      | String | Sí        | ID del endpoint de webhook |

**Requiere autenticación:** Sí

**Ejemplo de uso con AI:**

> "Rota el secreto del webhook wh\_ep\_a1b2c3d4"

<Warning>
  El secreto anterior deja de validar entregas inmediatamente. Actualiza tu receptor antes de rotar en producción.
</Warning>

***

<h2 id="listarentregaswebhook\">
  listarEntregasWebhook \\
</h2>

Lista el historial de entregas de un endpoint: estado, cantidad de intentos y código de respuesta recibido.

| Parámetro | Tipo   | Requerido | Descripción                        |
| --------- | ------ | --------- | ---------------------------------- |
| `id`      | String | Sí        | ID del endpoint de webhook         |
| `page`    | int    | No        | Página (inicia en 0, default: 0)   |
| `size`    | int    | No        | Elementos 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?"

***

<h2 id="reenviarentregawebhook\">
  reenviarEntregaWebhook \\
</h2>

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

| Parámetro    | Tipo   | Requerido | Descripción                 |
| ------------ | ------ | --------- | --------------------------- |
| `deliveryId` | String | Sí        | 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

<AccordionGroup>
  <Accordion title="Catálogo de eventos">
    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)](/api/webhooks#cat%C3%A1logo-de-eventos).
  </Accordion>

  <Accordion title="Firma Standard Webhooks">
    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)](/api/webhooks#verificaci%C3%B3n-de-firma).
  </Accordion>

  <Accordion title="Reintentos y anti-SSRF">
    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.
  </Accordion>
</AccordionGroup>