Este artículo también está disponible en:

Webhooks

En Flokzu puedes compartir la información contenida en tus formularios con sistemas externos a través de webhooks.
Los webhooks proporcionan un mecanismo para notificar a tu aplicación cuando se produzca un determinado evento y así poder tomar acciones. En Flokzu los eventos pueden ser de dos tipos:

Guardar
Tarea completada

Las acciones dependerán de tu sistema externo y deberás configurar la URL para ejecutarla.

¿Cómo funcionan los webhooks?

Imagina un sistema de timbre, el mismo incluye un botón en la puerta y una campana en tu sala de estar.
Cuando una persona presiona el botón, suena la campana en la sala, lo que te informa que alguien está en la puerta - es decir, una señal es enviada desde el botón al timbre.
En este ejemplo: alguien llegará a la puerta y presionará el botón, la campana escuchará el botón y sonará.

Los Webhooks funcionan de la misma manera, la puerta será Flokzu, el botón será el evento que sucede en Flokzu y la campana el sistema al cual notificarás de ese evento.
Para los webhooks: Sucederá un evento en Flokzu, el otro sistema escuchará ese evento y realizará una acción en base a ello, por ejemplo Actualizar datos.

Webhook de tipo guardar

Un webhook configurado para el evento guardar será ejecutado al momento de que se realice alguna de las siguientes acciones:

Crear una nueva instancia (ya sea ejecutada por un usuario logueado o desde un formulario público),
Al ejecutarse el auto guardado y el guardado explícito siempre que se hayan realizado cambios en el formulario.

WebHook de tipo tarea completada

Un webhook configurado para el evento tarea completada será ejecutado al momento de completar una tarea.

¿Cuándo NO se ejecuta un webhook? No se ejecutarán webhooks en caso de instancias creadas o actualizadas mediante la API de Flokzu, ni en tareas completadas por temporizador, ni por evento condicional.

Configurar webhooks

Los webhooks podrán ser habilitados y configurados para cada proceso. Para ello dirígete a la pestaña Configuración del proceso en cuestión y en la sección Webhooks podrás habilitarlo.

Allí podrás configurar las URLs que serán invocadas al ocurrir los diferentes tipo de eventos así como generar un token para agregar seguridad.

Formato general del mensaje enviado a los webhooks.

json
{ 
 "Timestamp": "Fecha de realizado el evento en formato UTC",
 "Type": "save o task_complete", 
 "Payload": "JSON de acuerdo al evento"
}

Formato del mensaje para un webhook de tipo guardar

En la propiedad Payload del json se enviará el documento completo que fue modificado.

El formato será el siguiente:

{
"tenantName": "nombre del tenant",
"reference": "referencia del doc",
"documentCreator": "creador del doc",
"dateCreated": "fecha creacion del documento",
"info": " resumen del documento",
"tags": ["tags del documento separados por coma"],
"downloadKey": "id documento",
"fields": [
                   {"campo 1": "valor 1"},
                   {"campo 2": "valor 2"}	
 ]
}

El json contiene el nombre del tenant al que pertenece el documento, su referencia, el creador del mismo y la fecha en que fue creado en formato ISO 8601.
También se encontraran el de los campos especiales resumen (en la propiedad info ) y tags (en la propiedad tags), asi como el ID de documento (propiedad downloadKey).

En la propiedad fields estarán todos los campos definidos por el usuario y los valores de estos se verán de la siguiente manera:

- Email, texto una línea, texto multilínea, link, entero, decimal, auto-calculado, fecha y hora: muestran el valor tal cual el documento.
- Combo y radio button: muestran el valor de la opción seleccionada
- Combo multiselección y checklist: muestran un array con las opciones seleccionadas con las comillas escapadas
- Tabla: muestra el nombre de la tabla y luego para cada fila, las columnas y sus valores.
- Adjunto: El archivo no es enviado, solamente se muestra información del mismo, nombre, attachment id, fecha de creación y más.
- Si/No: muestran true si la opción seleccionada es SI, en otro caso muestra false
- Rich text: muestra el contenido del campo con los tags que corresponda para generar el mismo contenido que se ve en el documento en Flokzu.
- Firma: la firma no es soportada.

Ejemplo:

json enviado:

{
   "tenantName": "Flokzu",
   "reference": "PED-14",
   "documentCreator": "leandro@flokzu.com",
   "dateCreated": "2019-08-06T17:17:10.223Z",
   "info": "",
   "tags": [""],
   "downloadKey": "b45602d6467856c5b2a45973c49a99e2",
   "fields": [
                {"Email": "nombre@gmail.com"},
                {"Nombre": "Juan Pérez"},
                {"Descripción": "Solicitud de insumos de papelería para oficinas"},
                {"Cantidad de artículos": "2"},
                {"Monto total": "3505.5"},
                {"Fecha": "06/08/2019"},
                {"Hora": "15:30:00"},
                {"Ciudad": "Madrid"},
                {"Forma de pago": "Contado"},
                {"Proveedores": "[\"Bolimax\",\"Rollerpen\",\"TodoUSB\"]"},
                {"Categoría": "[\"Papelería\",\"Informática\"]"}, 
                {"Pedido": [
                            {"Producto": "Bolígrafo",
                             "Cantidad": "150"
                             "Precio": "750"}, 
                            {"Producto": "Pendrive",
                             "Cantidad": "11"
                             "Precio": "2755.5"}
                           ]},
                {"Detalle del pedido": {
                                "attachmentId": "badbf0e134604c54907ac960a5f862c9",
                                "name": "detalle.pdf",
                                "mimeType": 50,
                                "superType": 0,
                                "creationTime": "2019-08-06T17:16:08.479Z",
                                "size": 47939,
                                "lastEditedUtc": "", 
                                "url": ""
                                    }},
                {"Cuenta activa": "true"},
                {"Web": "www.flokzu.com"},
                {"Cantidad de items": "161"},
                {"Observaciones": "<p style=\"text-align: center;\"><strong>Observaciones:</strong></p>\r\n<p style=\"text-align: center;\">&nbsp;</p>\r\n<p style=\"text-align: left;\">Realizar envío a Calle 1234 de 08 a 18 hs..</p>"}
              ]
}

Formato del mensaje para un webHook de tipo tarea completada

En la propiedad Payload del json se enviará la tarea y el usuario que la realizó.
A su vez se informará que acción fue llevada a cabo para completar la tarea y la fecha/hora correspondiente.
También se tendrá la información de la fecha en que fue creada la tarea (formato UTC).
El formato será el siguiente:

{
"task_name": "nombre de la tarea completada",
"last_participant": "usuario que completó la tarea",
"last_action": "decisión tomada para que la tarea se complete",
"reference": "referencia del doc",
"start_date": "fecha en que se creó la tarea",
"end_date": "fecha en que se completó la tarea"
}

La versión actual no prevé una política de reintentos. Para garantizar la integridad de los datos en tu implementación, puedes utilizar el timestamp del evento.
A manera de ejemplo, podría ser útil que controles que una llamada a tu web service que llega retrasada, no sobreescriba un dato en tu sistema que fue actualizado por una llamada posterior en el tiempo.

Probar los webhooks

Para probar como funcionan los webhooks puedes ingresar a https://webhook.site/. Este sitio te brindará una URL para tus pruebas.

Deberás colocar esa URL en la sección de Webhooks en la pestaña Configuración de tu proceso. Puedes utilizarla tanto para el evento de creación/ actualización de la instancia como para tarea completada.

Una vez agregada allí debes publicar el proceso, crear una instancia y/o completarla y verás el webhook en acción.

Respuesta de ejemplo de creación de instancia

Respuesta de ejemplo a tarea completada

Actualizado el: 21/07/2023

¿Este artículo te resultó útil?

¡Gracias!