Eventos, webhooks y observabilidad para integraciones
Qué ha cambiado
Cada actualización del contenido se versiona. Seleccione una versión para compararla con la anterior.
Versión 1 → 2
Actualización5 lecciones actualizadasduración
Actualización de contenido. Se notificó a los estudiantes inscritos.
La duración cambió de 13 a 17 minutos.
Una definición de webhook en Monosign está ligada a un tipo de auditoría. Cada auditoría de ese tipo crea una ejecución, y el servicio de webhooks envía la petición. En todos los proyectos surgen dos preguntas: por qué mi prueba llegó vacía y qué pasa cuando la cola de mensajes está caída.
::diagram api-webhook-delivery
### Los tokens proceden de la auditoría
En la ruta de auditoría, Monosign siempre aporta cinco claves, además de las claves de datos de ese tipo de auditoría:
| Token | Valor |
| --- | --- |
| `{{Audit.UserId}}` | El usuario al que se refiere el evento |
| `{{Audit.ActorUserId}}` | El usuario que realizó la acción |
| `{{Audit.SessionId}}` | La sesión |
| `{{Audit.ApplicationId}}` | La aplicación |
| `{{Audit.CreatedDate}}` | Cuándo se escribió la auditoría |
Los tokens se sustituyen en `URL`, `Headers` y `Body`. Un token que no es uno de estos cinco ni una clave de datos de la auditoría se sustituye por nada. Por eso un cuerpo copiado de un ejemplo con `{{UserId}}` llega al receptor con un valor vacío. Escriba `{{Audit.UserId}}`.
Una definición pequeña para un flujo de inicios de sesión tiene este aspecto:
```
Type: USER_LOGIN_SUCCESS
URL: https://siem.example/hook
Method: POST
Headers: {"X-Actor-Id": "{{Audit.ActorUserId}}"}
Body: {"user": "{{Audit.UserId}}", "at": "{{Audit.CreatedDate}}"}
```
### Qué demuestra `Execute` y qué no
`Execute` envía la petición con un conjunto de datos vacío. Demuestra que la URL es alcanzable, que el método y las cabeceras se aceptan y que el receptor responde a tiempo. No demuestra nada sobre sus tokens, porque cada token se genera como una cadena vacía. Para probar los tokens, provoque un evento de auditoría real de ese tipo, por ejemplo un inicio de sesión, y busque en `Items` de la definición una fila con `Send Success`.
### Reintentos
Un envío fallido se intenta hasta cinco veces, con una espera fija de un segundo entre intentos, y después la fila se marca como `Max Try Reached` y aparece en `Dead Letters`. Por eso el receptor tiene que tratar un evento repetido como inofensivo.
### Cuando la cola de mensajes está caída
::diagram obs-webhook-outage
En funcionamiento normal, la ejecución viaja por la cola de mensajes. Mientras el broker no es utilizable, el **host de servicio** entrega los webhooks directamente desde la base de datos en lotes acotados. La entrega continúa, y también continúa cuando Redis está caído.
La consecuencia práctica afecta a la red. Durante la caída, la conexión saliente hacia su receptor la abre el propio host de servicio. En un sitio con reglas de firewall por proceso o por host, el host de servicio necesita una regla de salida hacia el receptor del webhook. Si los eventos se detienen justo cuando falla el broker, compruebe primero esa regla.
Management, System, Services, `Dead Letters` es el lugar donde el trabajo que no llegó a entregarse espera a una persona. Un ingeniero de integración tiene que saber qué contiene la lista, qué deja fuera y qué hace realmente cada botón.
::diagram obs-dead-letters
### Qué se muestra
| Tipo | Aparece una fila cuando | Se muestra |
| --- | --- | --- |
| `Notifications` | Falló el propio despacho de la notificación y se agotaron sus reintentos | Los últimos 30 días |
| `User Provisions` | Una fila de aprovisionamiento está en estado de error, por ejemplo tras 48 horas sin completarse | Hasta 200 filas |
| `Webhooks` | Un webhook alcanzó su número máximo de intentos | Hasta 200 filas |
La lista pertenece siempre al tenant en el que ha iniciado sesión.
### Una lista vacía no demuestra salud
Tres límites hacen que una pestaña tranquila sea una señal débil:
- Una notificación cuyo correo, SMS o push falló **no** se muestra. El fallo se registra en la fila de historial de ese canal, y la notificación en sí termina igualmente como `Completed`. Solo un error a nivel de despacho deja aquí una notificación.
- Ve un único tenant y, para las notificaciones, solo los últimos 30 días.
- La página no alerta, no envía correo ni supervisa. Una fila solo es visible cuando alguien abre la página.
Trate la lista como una cola de trabajo que se revisa periódicamente y combínela con el historial de canales y con la supervisión de los sistemas receptores.
### Qué hacen los botones
| Tipo | `Requeue` | `Discard` |
| --- | --- | --- |
| Notificación | Vuelve a la espera, con una nueva caducidad de 24 horas | Estado final descartado |
| Aprovisionamiento de usuario | Vuelve a su estado de espera y el servicio de aprovisionamiento la recoge | Estado final descartado, no se envía nada |
| Webhook | La fila sale de la lista con el contador de intentos a cero, pero no se envía de nuevo | Estado final descartado |
Ambos botones actúan sobre una fila cada vez. Un elemento reencolado puede fallar de nuevo y volver a la lista. Un descarte conserva la fila y su último error en la base de datos, pero no se puede deshacer desde la pantalla.
La línea de los webhooks merece atención: como un webhook reencolado no se entrega, no use `Requeue` para reproducir un evento perdido. Provoque de nuevo el evento de negocio o haga que el receptor obtenga el estado actual a través de la API.
### Quién lo hizo
Ninguna de las dos acciones escribe columnas de auditoría en la fila. Cada una escribe una línea en el registro de Management:
```
Dead letter requeued: webhook 7d0c... by 41aa...
Dead letter discarded: userprovision 92be... by 41aa...
```
La línea lleva el tipo (`notification`, `userprovision` o `webhook`), el ID de la fila y el ID del usuario. Para un descarte, esta línea es el único registro. Si un auditor puede preguntar quién retiró una fila, conserve los registros de Management el tiempo suficiente para responder.
Monosign ofrece dos familias de endpoints de salud, sin autenticación, en las aplicaciones API y Management. Responden a preguntas distintas, y elegir el equivocado provoca puntos ciegos o reinicios innecesarios.
### Las dos familias
| Endpoint | Qué comprueba | Respuesta |
| --- | --- | --- |
| `GET /ping/hc` | Una lista de comprobaciones: `Database`, `Mq`, `Cache`, `ServerGC`, `License` | 200 `{"IsHealthy":true}`, o 400 con las entradas que fallan |
| `GET /ping/hc/mq` (solo API) | Una dependencia; `db`, `cache` y otras funcionan igual | El veredicto de esa única comprobación |
| `GET /probes/ready` | Solo la base de datos. El estado de la caché se informa pero no se juzga | 200, o 503 `not ready` |
| `GET /probes/live`, `/probes/startup` | Para orquestadores | 200 mientras el proceso atiende |
### Cuál para cada consumidor
- **Un orquestador que reinicia un contenedor cuando falla** debe usar `/probes/ready`. Un problema del broker hace que `/ping/hc` no esté sano, y reiniciar el contenedor de la API no repara un broker. La disponibilidad mira solo la base de datos, así que no provoca reinicios por un fallo que un reinicio no puede arreglar.
- **Un balanceador de carga** debe usar el `/ping/hc` completo, donde cualquier comprobación que falle cambia `IsHealthy` y el nodo sale de la rotación.
- **Un monitor de una sola dependencia** debe usar la forma dirigida, por ejemplo `/ping/hc/mq`.
::diagram obs-health-probes
### Dé al monitor al menos seis segundos
La comprobación `Mq` es un recorrido real de ida y vuelta por el broker, con un tiempo de espera de sonda de cinco segundos. Un broker degradado hace que toda la respuesta tarde eso. Un monitor externo con un tiempo de espera inferior a seis segundos informa de su propio tiempo agotado antes de que Monosign pueda informar del motivo real.
### Supervisión de la cola de mensajes desde v2026.10
En v2026.10 cambiaron dos cosas. Los fallos de salud se cuentan por minuto y se muestran en la página `Status` como minutos con fallo por día. Y la cola de mensajes ya no se comprueba de forma centralizada, porque el broker pertenece a cada centro de datos. Un monitor de Monosign que vigile el servicio central `mq` permanece por tanto en silencio durante una caída del broker. El `/ping/hc` de cada nodo sigue incluyendo la entrada `Mq`, así que dirija la supervisión a los nodos.
Cuando una llamada REST falla o un envío no llega, necesita el registro del componente correcto. Monosign le ofrece tres formas de obtenerlo, y cada una tiene un límite claro.
| Forma | Cubre | Límite |
| --- | --- | --- |
| Salida del contenedor | Todos los componentes, de forma continua | Necesita su propia canalización de registros |
| Management, System, `Logs` | Management y los procesos de servicio conectados a él | Ni API ni Account; solo se guarda en memoria |
| Management, System, `Tracing & Log` | Las aplicaciones que seleccione, durante un número fijo de minutos | Algunas aplicaciones no tienen recolector |
::diagram obs-log-paths
### Salida del contenedor y líneas JSON
Cada proceso escribe su registro en stdout como texto sin formato. Desde v2026.10, establecer `MONOSIGN_LOG_FORMAT=json` en un componente hace que cada línea de stdout de ese proceso sea un objeto JSON, que es lo que espera una canalización de líneas JSON. Tres detalles importan al configurarlo:
- La variable se lee por componente, así que establézcala en cada contenedor del que recoja registros.
- Cubre **solo stdout**. stderr no cambia, por lo que el informe de fallo del entorno de ejecución sigue llegando como texto sin formato. Una canalización tiene que tolerar esas pocas líneas.
- Un valor distinto de `json` o `text` vuelve a texto con una línea de aviso. El arranque nunca falla por ello.
### La página Logs
La página transmite eventos del proceso Management y de los procesos de servicio que tienen `MONOSIGN_LOG_HUB_URL` apuntando a Management. Las aplicaciones API y Account nunca envían sus eventos allí, y las casillas de `Apps` no filtran nada. Si está depurando llamadas REST fallidas, esta página no puede mostrar el lado de la API.
Los eventos viven en la memoria de una instancia de Management, hasta 100 000, y desaparecen tras un reinicio.
`Configure` contiene un ajuste que se lee al revés. `Default Level` **descarta** los eventos del nivel elegido o inferiores:
| `Default Level` | Qué ve |
| --- | --- |
| `Verbose` | Todo lo que está por encima de Verbose, lo máximo que puede mostrar la página |
| `Warning` (por defecto) | Error y Fatal |
| `Error` | Solo Fatal |
Para ver errores, el nivel debe ser inferior a Error. El ajuste solo filtra la página. No cambia lo que registran los procesos.
### Tracing & Log
Una traza captura toda la salida de registro de las aplicaciones de servidor seleccionadas durante `Duration` minutos y ofrece el resultado como un zip. Es la herramienta para las aplicaciones API y Account.
Seleccione solo aplicaciones que puedan responder. `Monosign - Access Gateway` y `Monosign - RADIUS Server` aparecen en la lista pero no tienen recolector, de modo que una traza que las incluya nunca termina: se queda en `Started`, y `Download` indica que hay aplicaciones en curso. Use `Download Partial` para obtener lo recogido y deje fuera esas dos la próxima vez. `Force Start` e `Interval` del formulario se guardan pero no se usan, y la retención de datos no elimina las trazas, así que borre usted las antiguas.
> Consejo: Parta del componente, no de la herramienta. Para el lado de API o Account use `Tracing & Log` o la salida del contenedor. La página `Logs` solo puede mostrar Management y los procesos de servicio conectados a él.
Monosync tiene cuatro señales. Cada una responde bien a una pregunta y calla sobre otras, y de un ingeniero de integración se espera que sepa distinguirlas.
| Señal | Pregunta que responde | Lo que no le dice |
| --- | --- | --- |
| `/ping/hc` | ¿Está la instalación en pie y están vivos los nodos de servicio? | Si una integración concreta funciona |
| `Integration Logs` | ¿Qué hizo una ejecución con un registro? | Nada entre ejecuciones ni fuera de Monosync |
| `Monitoring` | ¿Falló una integración o dejó de ejecutarse? | Nada, si su vía de correo no está configurada |
| `Audits` | ¿Quién cambió la configuración en la interfaz web? | Los cambios hechos por otras vías |
### La respuesta de salud tiene dos campos
```
GET /ping/hc
{"IsHealthy":true,"InstanceCount":3}
```
`InstanceCount` es el número de nodos de servicio que están informando. Esos nodos ejecutan las integraciones. Una respuesta `{"IsHealthy":true,"InstanceCount":0}` sigue siendo HTTP 200 y, sin embargo, ninguna integración puede ejecutarse, por ejemplo porque el rol de servicio está deshabilitado en todos los nodos. Una sonda que solo mira `IsHealthy` no lo detecta, así que alerte también cuando el recuento sea cero.
### Leer una ejecución
La página de registros desciende desde la ejecución a sus acciones, a los objetos que tocó una acción y a los valores cambiados de un objeto. Cuando un trabajo falla solo para algunos usuarios, empiece aquí: el motivo está en la fila del objeto, en `Status`, `Message` y `Exception`, y los fallos de mapeo se recogen en `Mapping error(s) found!`.
Dos límites importan a un equipo de operaciones de seguridad:
- `Export All` exporta los valores cambiados de la ejecución. No exporta errores.
- Monosync no envía sus registros a ningún sitio. Un SIEM, o cualquier vista entre ejecuciones, necesita una consulta de solo lectura sobre las tablas de registro. Léalas antes de que la retención de registros purgue las filas.
### Los monitores necesitan la API de Monosign
Un monitor abre una incidencia cuando una integración tiene errores o no se ha ejecutado durante un tiempo fijado, y envía un aviso `[DOWN]`, recordatorios y un aviso `[UP]` al recuperarse. Los monitores no tienen un ajuste de servidor de correo propio. El correo y el push pasan por la API de Monosign, configurada en el nodo de interfaz con `MONOSIGN_API_URL`, `MONOSIGN_APPID` y `MONOSIGN_APPKEY`.
Si alguna de las tres está vacía, el envío se omite, pero la incidencia se marca igualmente como notificada. Esos avisos se pierden definitivamente. Después de añadir las variables, espere correo solo para nuevos cambios de estado y recordatorios, y avise al equipo de operaciones de que los avisos DOWN anteriores no llegarán.
::diagram obs-monitor-notify
### Una lista Audits vacía no es una prueba
Monosync escribe una fila de auditoría para los cambios de configuración hechos en la interfaz web. Varias vías no escriben ninguna:
- Los cambios mediante la API REST v1, como un ajuste de origen o el valor de una variable.
- Una importación de ajustes.
- Los commits de creación y actualización de la propia interfaz, cuando la instalación funciona con `MONOSYNC_COMMIT_DISABLE=true`.
Cuando los ajustes de un origen cambiaron durante la noche y `Audits` no muestra nada, la conclusión no es que nadie los cambió. Compruebe quién tiene la clave de API y si se ejecutó una importación.