WebHooks
Introducción
Webhook invierte el flujo de comunicación y permite que los sistemas se comuniquen de manera mucho más ágil y eficiente en respuesta a eventos. Los Roteadores a veces pueden tardar para responder a una requisición en algunas condiciones, como por ejemplo:
- Dispositivo desconectado (responderá cuando se inicia)
- URL o contraseña de Force Connection incorrecta
- Acciones como reboot o reset, que llevan tiempo para ocurrir
Funcionamiento
Al recibir una requisición cadastrada en WebHooks, la API responderá con un mensaje de confirmación de recepción, con un número de protocolo que identifica todas las acciones relacionadas con la requisición.
El número de protocolo es un UUID de 32 caracteres, con grupos separados por hífens. Todas las respuestas enviadas por medio de WebHooks y que deriven de una requisición, tendrán el mismo UUID.
Métodos soportados
Los métodos soportados indican que WebHook se utilizará para notificar el resultado de una acción iniciada por el IXC/Cliente API:
- devices/parameters/update/: Notifica el estado de la actualización de parámetros.
- /api/v1/devices/reboot: Notifica si la orden de reboot (reinicialización) fue ejecutada con éxito o fallo en el dispositivo.
Funcionamiento de WebHook
Para ilustrar el funcionamiento de WebHook en el contexto de los métodos soportados (Update y Reboot), el escenario se ajusta para mostrar la notificación del resultado de una acción remota, en lugar de sólo la caída de conexión.
Escenario 1: Usando Webhook (Comunicación Activa) - Notificación de salida
En este modelo, Servidor (API) notifica el Cliente API/IXC ACS sobre el resultado de una acción solicitada anteriormente, así como el dispositivo la concluye.
- Ación solicitada: IXC ACS envía una requisición a la API solicitando el Reboot del Roteador RTR-42.
- Configuración: IXC ACS ya informó a la API su Webhook URL para notificaciones de conclusión (ex:
https://monitoramento.ixc.com/resultado). - Gatijo: El Roteador RTR-42 concluye la reanudación (o el fallo ocurre) a las 10:07:00h.
- Ación: La API, instantáneamente, envía una requisición
POSTa Webhook URL con payload detallando el resultado (ex:{"protocolo": "UUID-DO-REBOOT", "router_id": "RTR-42", "status": "success", "timestamp": "10:07:00"}). - Resultado: IXC ACS recibe la notificación en tiempo real, actualizando el estado de la orden en los dashboards y prosiguiendo con el flujo de trabajo.
Vantaje principal: El sistema solicitante (IXC ACS) no necesita esperar ni preguntar, se le advierte así que la acción que puede llevar tiempo es concluida o falha.
Escenario 2: Usando API Tradicional (Polling) - Verificación de salida
En este modelo, el IXC ACS necesitaría verificar activamente el estado de la orden en el router.
- Ación solicitada: IXC ACS envía la requisición de Reboot a la API a las 10:05:00h.
- Configuración: El IXC ACS está configurado para, por ejemplo, cada 5 minutos, preguntar a la API sobre el estado de la orden.
- Gatijo: El Roteador concluye el reboot a las 10:07:00h.
- Ación:
10:05:00h: Orden de Reboot enviado.
10:07:00h: Reboot terminado. El IXC ACS no sabe eso.
10:10:00h: IXC ACS hace la primera requisición de polling para la API: "¿La orden X fue terminada?" (Recibió el estatus de éxito).
- Resultado: El estado de la orden solo se actualiza en el IXC ACS en 10:10:00h, resultando en un traso de 3 minutos entre la conclusión de la acción y la actualización del sistema. Desventaje principal: El sistema solicitante queda guardando (o verificando) por un tiempo indeterminado, y la actualización del estado depende del intervalo de polling .
Glosario
| Termo | Significado |
|---|---|
| Timeout | Tempo agotado |
| WebHook | Retorno de llamada web (Mecanismo de notificación activa) |
Consideraciones Finales
Es fundamental activar los WebHooks correctamente y seguir las prácticas de seguridad en la configuración. La comprensión de los métodos soportados y números de protocolo contribuye a una integración eficiente, especialmente cuando se trata de acciones que pueden llevar tiempo, como reboot y update de parámetros.