El siguiente diagrama sirve para explicar cuál es el ciclo de vida de una llamada a un Web Hook.
Actores
Primero, revisemos los elementos que participan:
- Plataforma BlizWork: Corresponde a todos los recursos que conforman el sistema, incluyendo los usuarios y roles, los flujos de trabajo y formularios, los casos, las bases de datos maestras, etc. Esta plataforma reside en una nube de servicios y se accede a través de la aplicación web.
- Coordinador de Ejecución de Caso: Son los módulos de BlizWork que se encargan de orquestar los procesos en la medida que estos son ejecutados por los usuarios.
- Coordinador de Llamados Web Hook: Es un módulo que se encarga de coordinar el llamado a los servicios web externos en la medida que estos se invocan, dejando registro de todo lo que ocurre en estas ejecuciones. Este registro es el que se utiliza para, desde el Servidor Externo, validar que una llamada sea legítima.
- API (Application Program Interface): Es un componente que permite coordinar y controlar el acceso a los recursos internos de BlizWork desde aplicaciones externas, incluyendo Web Hooks.
- Servidor Externo: Es un servidor que puede residir tanto en un proveedor de recursos computacionales en la nube, como Microsoft Azure o Amazon Web Services, como un servidor provisto por el desarrollador. En este último caso, el servidor debe ser visible en Internet en una dirección IP o nombre de host conocidos. La provisión, administración y disponibilidad de este servidor, sea físico o virtual, es responsabilidad del Cliente o Partner que implementa este servicio.
- Web Hook: Es una rutina implementada por el desarrollador y que es llamada cuando ocurre algún evento predeterminado en un flujo de trabajo y sirve para realizar tareas complementarias, tales como guardar datos en una base de datos, ejecutar transacciones en un ERP, enviar eventos a otras plataformas web, guardas datos de monitoreo y estadísticas, y cualquier otra necesidad que pudiera tener una organización. Este componente de software es diseñado, implementado y mantenido por un desarrollador y no está dentro del ámbito de control de BlizWork.
Ciclo de Vida
Ahora revisemos el ciclo de vida de una llamada a Web Hook considerando las distintas circunstancias que se puedan dar en un caso real.
Supongamos que tenemos un flujo de trabajo que en algún momento pasa de la Tarea o formulario 1 a la Tarea o formulario 2. El proceso se ha configurado para que esta acción invoque un web hook. Es decir, cuando el usuario presione el botón para pasar a la Tarea 2, junto con pasar a esta tarea, se invocará el web hook.
Es importante tener en cuenta que el llamado al web hook se realizará de manera asincrónica. Es decir, no se esperará al término del web hook para pasar a Tarea 2. Tampoco se considera el resultado del web hook para condicionar el paso a Tarea 2. Concretamente, si el web hook no responde, responde con un código de error o responde correctamente, de igual modo y en cualquiera de los casos se pasará a la tarea siguiente.
De cualquier modos, con este evento (acción) se iniciará el ciclo de vida de la llamada que se describe a continuación.
1. Registro de Llamada
En la Tarea 1, el flujo de trabajo tiene asociado un web hook a la acción. Cuando el usuario selecciona esta acción, el control pasa del módulo de coordinación de Ejecución de Caso al módulo de coordinación de Llamados a Web Hook.
Junto con realizar esta acción, la ejecución continua al siguiente formulario Tarea 2.
El Coordinador de Llamados a Web Hook deja registro del llamado y genera un “token” (testigo) de llamado a la URL que se haya especificado para el web hook. Hay que recordar que un web hook es un servicio web que se invocará mediante una llamada POST de HTTP, pasándole una serie de datos acerca del caso, el proceso, el usuario y la organización. Los datos que se pasan al web hook se detallan más abajo.
2. Llamada al Web Hook
Una vez que se ha dejado registro del intento de llamado, este es efectivamente realizado pasando los parámetros estándares de la llamada (ver más abajo). Dentro de los parámetros enviados mediante POST al hook, se encuentra el token generado en el paso anterior.
Si el llamado genera un error inmediatamente, este queda registrado y termina el ciclo de vida del hook. Por ejemplo, si la URL no está correctamente indicada o el servicio no está disponible, se puede recibir un error 404 indicando que el servicio no existe.
3. Validación de la Llamada
Se recomienda que lo primero que haga el hook, sea validar que la llamada es válida, es decir, que la invocación del servicio web fue efectivamente realizada por BlizWork.
¿Por qué se recomienda esta validación? Exclusivamente por seguridad. Ya que la plataforma BlizWork tiene una arquitectura distribuida en micro-servicios, no se puede anticipar desde qué servidor se realizará la llamada al web hook, por lo tanto no se puede confiar en una dirección IP o nombre de host específico.
La alternativa de utilizar certificados de seguridad es compleja, sobre todo en plataformas que no tienen un manejo simple de los certificados raíz y de autoridades de certificación que son esenciales para utilizar certificados X.509 de manera efectiva.
Dada estas condiciones, BlizWork proporciona un método en su API que permite realizar la validación de una llamada de manera programática. Si la llamada es válida, se tendrá una respuesta positiva. Si la llamada no es válida, se recibirá un código de estado de error.
4. Resultado de la Validación de Llamada
Se recomienda que sea la primera actividad del hook porque el token de validación tiene una validez de 60 segundos (1 minuto). Es decir, si la validación se realiza pasado este lapso, se obtendrá un estado de token expirado.
Por otro lado, no es conveniente que el hook desperdicie recursos computacionales en llamadas inválidas. De hecho, en caso de llamadas inválidas, ni siquiera es recomendable responder, ya que esto entrega información a un posible hacker que esté examinando puntos de ataque.
Si la llamada es válida, el hook puede realizar las tareas normales para las cuales se ha implementado. Por ejemplo, puede realizar otras llamadas a la API de BlizWork para obtener datos o ejecutar procesos automatizados.
5. Respuesta a la Llamada
Es recomendable que la respuesta a BlizWork se envíe lo antes posible, ya que BlizWork no utiliza un plazo de expiración (timeout), por lo que habrá recursos reservados hasta que se reciba una respuesta desde el hook.
Se recomienda que todas las respuestas correctas tengan el código de estado estándar 20X, mientras que se usen otros códigos para situaciones de error. De esta forma, al consultar el registro de llamadas, se podrá identificar fácilmente cuales llamadas han resultado exitosas y cuales no. Esto es una gran ayuda en caso de auditoría, diagnóstico de errores y resolución de problemas comunes (troubleshooting).
BlizWork solo registra el llamado al hook y su respuesta. Mensajes de depuración y auditoría del servicio deben ocurrir dentro del Servidor Externo y son responsabilidad del desarrollador y/o administrador de sistemas de la plataforma externa a BlizWork.