Artículos sobre: Admins & desarrolladores

Webhooks: enviar tus datos del formulario a sistemas externos

En INTEGRADOC 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 INTEGRADOC los eventos pueden ser de dos tipos:

Guardar
Tarea completa

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á INTEGRADOC, el botón será el evento que sucede en INTEGRADOC y la campana el sistema al cual notificarás de ese evento.
Para los webhooks: Sucederá un evento en INTEGRADOC, 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 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 completa

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

¿Cuándo NO se ejecuta un webhook? No se ejecutarán webhooks en caso de tareas eliminadas o completadas por temporizador o eventos condicionales.

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 en el header de la llamada para brindarle seguridad a la misma.

Formato general del mensaje enviado a los webhooks.

{ 
 "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 property 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 property info ) y tags (en la property tags), asi como el ID de documento (property downloadKey).

En la property 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 un json con el nombre de la columna y su respectivo valor
- Adjunto, 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 INTEGRADOC.
- Firma, manda información propia del componente utilizado.

Ejemplo:

json enviado:

{
   "tenantName": "IDOC",
   "reference": "TODLTC-14",
   "documentCreator": "lmorat@integradoc.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": "2020/12/06"},
                {"Hora": "15:30:00"},
                {"Ciudad": "Montevideo"},
                {"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.integradoc.com"},
                {"Cantidad de ítems": "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 Av. Fco. Soca 1531 de 08 a 18 hs..</p>"}
              ]
}

Formato del mensaje para un webHook de tipo tarea completa

En la property 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 correspondeinte.
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 completo la tarea",
	"last_action": "decisión tomada para que la tarea se complete",
	"reference": "referencia del doc",
	"start_date": "fecha en que se creo la tarea",
	"end_date": "fecha en que se completo la tarea"
}

Política de reintentos e integridad de datos

En caso de que la comunicación con el sistema externo se pierda momentáneamente, INTEGRADOC prevé el reintento de envío de datos en intervalos de tiempo que se incrementan exponencialmente (hasta un día después) y hasta un máximo de 20 reintentos.

Ten en cuenta que en tu implementación debes controlar que un dato proveniente de un reintento no sobreescriba un dato posterior de la misma instancia, controlando el timestamp del evento.

Actualizado el: 16/09/2020

¿Este artículo te resultó útil?

¡Gracias!