Webhooks - Documentación de Flexxible

Webhooks es una funcionalidad que permite integrar la plataforma con herramientas de terceros para el envío de notificaciones cuando se producen determinados eventos en la organización. Eventos disponibles:

Alerta activada
Microservicio ejecutado
Objeto creado
Objeto modificado
Objeto eliminado
Operación ejecutada
Operación ejecutada en un workspace

Cuando ocurre uno de estos eventos, la plataforma realiza una llamada HTTP a la URL configurada por la organización y envía un mensaje con la información correspondiente. La aplicación de destino puede usar estos datos para ejecutar acciones como crear un ticket en un sistema ITSM, enviar un mensaje por Slack o Microsoft Teams, mandar un correo electrónico, entre otros. Esta herramienta solo puede ser configurada por un usuario con rol de Administrador de organización.

Vista general

La pantalla principal muestra el listado de webhooks configurados en la organización, indicando si están habilitados o deshabilitados. La tabla incluye:

Nombre. Nombre asignado al webhook. Al hacer clic se accede a su vista de detalle.
Tipo de evento. Evento que activará el webhook.
URL de destino. Dirección del sistema externo que recibe el evento y actúa según la información proporcionada en el mensaje.
Estado. Indica si el webhook está Habilitado o Deshabilitado.

Crear una integración webhook

Para crear un nuevo webhook se deben seguir los siguientes pasos:

Acceder a Configuración → Integraciones Webhook.
Hacer clic en Nuevo.
Rellenar y configurar cada sección del formulario:

Visión general

Nombre. Nombre asignado al webhook.
Tipo de evento. Evento que activará el webhook.
URL de destino. Dirección del sistema externo que recibe el evento y actúa según la información proporcionada en el mensaje.

Elementos

El contenido de esta tabla depende del tipo de evento seleccionado.

Alerta activada
- Muestra el listado de alertas activas de la organización para seleccionar cuáles enviarán el webhook.
- Enviar webhook para todas las alertas - Activa el webhook para todas las alertas.
Microservicio ejecutado
- Muestra el listado de microservicios habilitados para seleccionar cuáles enviarán el webhook.
- Enviar webhook para todos los microservicios - Activa el webhook para todos los microservicios.
- En ambos casos, el botón Ver permite acceder a la vista de detalle del recurso.
Objeto creado, Objeto modificado u Objeto eliminado
- Muestran un listado para seleccionar el objeto que enviará el webhook tras la acción correspondiente.
- Enviar webhook para todos los objetos - Activa el webhook para todos los objetos.
Operación ejecutada
- Muestra un listado para seleccionar la operación que enviará el webhook cuando se ejecute.
- Enviar webhook para todas las operaciones - Activa el webhook para todas las operaciones.
Operación ejecutada en un workspace
- Muestra un listado para seleccionar la operación que enviará un webhook por cada dispositivo en el que se ha ejecutado.
- Enviar webhooks para todas las operaciones ejecutadas en cada workspace - Activa el webhook para todas las operaciones por dispositivo.
- Las operaciones pueden ejecutarse en uno o más dispositivos.
- El evento Operación ejecutada permite enviar un webhook a nivel global.
- El evento Operación ejecutada en un workspace permite enviar un webhook por cada uno de los dispositivos en los que se ha ejecutado la operación. Ejemplo: Si se ejecuta la operación Reiniciar en tres dispositivos simultáneamente, se generarán:
  - Una notificación webhook de tipo Operación ejecutada.
  - Tres notificaciones webhook de tipo Operación ejecutada en un workspace.

Configuración del mensaje

En este apartado se define el mensaje que se enviará cuando ocurra el evento. La configuración utiliza formato JSON y determina la estructura y el contenido del mensaje transmitido al sistema externo. Las variables se sustituyen automáticamente por valores reales cuando se produce el evento.

Hacer clic en Guardar.

Una organización no debería tener dos webhooks con la misma configuración porque podría generar envíos duplicados.

Variables disponibles para el mensaje

Todos los tipos de eventos

Variables	Descripción
#event_type	Tipo de evento
#organization_id	ID de la organización
#organization_name	Nombre de la organización/inquilino
#timestamp	Fecha y hora del evento (ISO 8601)

Alerta activada

Variables	Descripción
#alert_name	Nombre de la alerta
#alert_information	Información adicional de la alerta
#alert_start	Fecha y hora de inicio de la alerta (ISO 8601)
#alert_element	Elemento que disparó la alerta
#workspace_id	ID del workspace
#workspace_name	Nombre del workspace
#workspace_last_user	Último usuario que usó el workspace
#workspace_reporting_group_id	ID del grupo de reporte
#workspace_reporting_group_name	Nombre del grupo de reporte
#workspace_internal_id	Workspace internal ID

Ejemplo de plantilla

{
    "message": {
        "event_type": "#event_type",
        "organization_id": "#organization_id",
        "organization_name": "#organization_name",
        "workspace_id": "#workspace_id",
        "workspace_name": "#workspace_name",
        "workspace_last_user": "#workspace_last_user",
        "reporting_group_id": "#workspace_reporting_group_id",
        "reporting_group_name": "#workspace_reporting_group_name",
        "alert_name": "#alert_name",
        "alert_information": "#alert_information",
        "alert_start": "#alert_start",
        "alert_element": "#alert_element",
        "timestamp": "#timestamp"
    }
}

Microservicio ejecutado

Variables	Descripción
#operation_id	ID de la operación ejecutada
#microservice_id	ID del microservicio
#microservice_name	Nombre del microservicio
#operation_startdate	Fecha y hora de inicio de la operación (ISO 8601)
#operation_enddate	Fecha y hora de fin de la operación (ISO 8601)
#operation_result	Resultado de la operación (Completed, Error, Timeout o Cancelled)
#workspace_id	ID del workspace
#workspace_name	Nombre del workspace
#workspace_last_user	Último usuario que usó el workspace
#workspace_reporting_group_id	ID del grupo de reporte
#workspace_reporting_group_name	Nombre del grupo de reporte
#operation_startedby	Usuario o componente que inició la ejecución del microservicio
#workspace_internal_id	Workspace internal ID

Ejemplo de plantilla

{
    "message": {
      "event_type" : "#event_type",
      "organization_id" : "#organization_id",
      "organization_name" : "#organization_name",
      "timestamp" : "#timestamp",
      "workspace_id" : "#workspace_id",
      "workspace_name" : "#workspace_name",
      "workspace_last_user" : "#workspace_last_user",
      "reporting_group_id" : "#workspace_reporting_group_id",
      "reporting_group_name" : "#workspace_reporting_group_name",
      "operation_id": "#operation_id",
      "microservice_id": "#microservice_id",
      "microservice_name": "#microservice_name",
      "operation_startdate": "#operation_startdate",
      "operation_enddate": "#operation_enddate",
      "operation_result": "#operation_result"
    }
}

Objeto creado, modificado o eliminado

Variables	Descripción
#event_type	Tipo de evento
#organization_id	ID de la organización
#organization_name	Nombre de la organización/inquilino
#timestamp	Fecha y hora del evento (ISO 8601)
#entity_type	Tipo de entidad
#entity_name	Nombre de la entidad
#entity_id	ID de la entidad
#action	Acción realizada (Creación, Modificación o Eliminación)
#triggered_by_name	Nombre del usuario que disparó el evento
#triggered_by_email	Dirección de correo electrónico del usuario que disparó el evento
#triggered_by_id	ID del usuario que disparó el evento

Ejemplo de plantilla

{
  "message": {
    "event-type": "#event_type",
    "organization": {
      "id": "#organization_id",
      "name": "#organization_name"
    },
    "entity": {
      "entity-type": "#entity_type",
      "object-name": "#entity_name",
      "object-id": "#entity_id"
    },
    "metadata": {
      "action": "#action",
      "timestamp": "#timestamp",
      "user-name": "#triggered_by_name",
      "useremail": "#triggered_by_email",
      "user-id": "#triggered_by_id"
    }
  }
}

Operación ejecutada

Variables	Descripción
#event_type	Tipo de evento
#timestamp	Fecha y hora del evento (ISO 8601)
#organization_id	ID de la organización
#organization_name	Nombre de la organización/inquilino
#operation_type	Tipo de operación
#description	Descripción de la operación
#status	Estado actual de la ejecución de la operación
#summary	Resumen de la operación (JSON)
#started_by	Usuario que inició la operación
#created_at	Fecha y hora de creación de la operación (ISO 8601)
#started_at	Fecha y hora de inicio de la operación (ISO 8601)
#finished_at	Fecha y hora de finalización de la operación (ISO 8601)
#total_workspaces	Número total de workspaces procesados
#total_warnings	Número total de ejecuciones con advertencias durante la operación
#total_errors	Número total de ejecuciones con errores durante la operación
#flow_id	ID del flujo asociado
#microservice_id	ID del microservicio asociado
#fra_type	Tipo de Flexxible Remote Assistance (FRA)
#fra_start	Fecha y hora de inicio de Flexxible Remote Assistance (FRA) (ISO 8601)
#fra_end	Fecha y hora de fin de Flexxible Remote Assistance (FRA) (ISO 8601)

Ejemplo de plantilla

{
  "message": {
    "event_type": "#event_type",
    "timestamp": "#timestamp",
    "organization": {
      "id": "#organization_id",
      "name": "#organization_name"
    },
    "operation": {
      "type": "#operation_type",
      "description": "#description",
      "status": "#status",
      "summary": "#summary",
      "started_by": "#started_by",
      "created_at": "#created_at",
      "started_at": "#started_at",
      "finished_at": "#finished_at"
    },
    "results": {
      "total_workspaces": "#total_workspaces",
      "total_warnings": "#total_warnings",
      "total_errors": "#total_errors"
    },
    "context": {
      "flow_id": "#flow_id",
      "microservice_id": "#microservice_id",
      "fra_type": "#fra_type",
      "fra_start": "#fra_start",
      "fra_end": "#fra_end"
    }
  }
}

Operación ejecutada en un workspace

Variables	Descripción
#event_type	Tipo de evento
#timestamp	Fecha y hora del evento (ISO 8601)
#organization_id	ID de la organización
#organization_name	Nombre de la organización/inquilino
#operation_type	Tipo de operación
#description	Descripción de la operación
#operation_status	Estado de la operación
#started_by	Usuario que inició la operación
#created_at	Fecha y hora de creación de la operación (ISO 8601)
#started_at	Fecha y hora de inicio de la operación (ISO 8601)
#finished_at	Fecha y hora de fin de la operación (ISO 8601)
#operation_flow_id	ID del flujo asociado a la operación
#operation_microservice_id	ID del microservicio asociado a la operación
#operation_fra_type	Tipo de Flexxible Remote Assistance (FRA)
#operation_fra_start	Fecha y hora de inicio de Flexxible Remote Assistance (FRA)(ISO 8601)
#operation_fra_end	Fecha y hora de fin de Flexxible Remote Assistance (FRA) (ISO 8601)
#workspace_id	ID del workspace
#workspace_name	Nombre del workspace
#workspace_last_user	Último usuario que usó el workspace
#workspace_reporting_group_id	ID del grupo de reporte
#workspace_reporting_group_name	Nombre del grupo de reporte
#workspace_operation_result	Resultado de la operación en el workspace
#workspace_operation_startdate	Fecha y hora de inicio de la operación en el workspace (ISO 8601)
#workspace_operation_enddate	Fecha y hora de finalización de la operación en el workspace (ISO 8601)
#workspace_internal_id	Workspace internal ID

Ejemplo de plantilla

{
  "message": {
    "event_type": "#event_type",
    "timestamp": "#timestamp",
    "organization": {
      "id": "#organization_id",
      "name": "#organization_name"
    },
    "operation": {
      "type": "#operation_type",
      "description": "#description",
      "status": "#operation_status",
      "started_by": "#started_by",
      "created_at": "#created_at",
      "started_at": "#started_at",
      "finished_at": "#finished_at"
    },
    "context": {
      "flow_id": "#operation_flow_id",
      "microservice_id": "#operation_microservice_id",
      "fra_type": "#operation_fra_type",
      "fra_start": "#operation_fra_start",
      "fra_end": "#operation_fra_end"
    },
    "workspace": {
      "id": "#workspace_id",
      "name": "#workspace_name",
      "last_user": "#workspace_last_user",
      "reporting_group": {
        "id": "#workspace_reporting_group_id",
        "name": "#workspace_reporting_group_name"
      }
    },
    "execution": {
      "result": "#workspace_operation_result",
      "start_date": "#workspace_operation_startdate",
      "end_date": "#workspace_operation_enddate"
    }
  }
}

Slack

A continuación, se muestra un ejemplo de plantilla compatible con Slack Incoming Webhooks, que puede utilizarse como base para construir el mensaje enviado desde la plataforma:

{
  "text": "*Flexxible microservice was executed*",
  "blocks": [
    {
      "type": "section",
      "fields": [
        {
          "type": "mrkdwn",
          "text": "*Microservicio:*\n#microservice_name"
        },
        {
          "type": "mrkdwn",
          "text": "*Resultado:*\n#operation_result"
        }
      ]
    },
    {
      "type": "section",
      "fields": [
        {
          "type": "mrkdwn",
          "text": "*Organización:*\n#organization_name"
        },
        {
          "type": "mrkdwn",
          "text": "*Workspace:*\n#workspace_name"
        }
      ]
    },
    {
      "type": "section",
      "fields": [
        {
          "type": "mrkdwn",
          "text": "*Inicio:*\n#operation_startdate"
        },
        {
          "type": "mrkdwn",
          "text": "*Fin:*\n#operation_enddate"
        }
      ]
    }
  ]
}

Para más información sobre el formato de mensajes, los bloques disponibles y las mejores prácticas, consulta la guía oficial de Slack.

Microsoft Teams

En Microsoft Teams, las plantillas se pueden consultar directamente desde la configuración de cada canal.

Para obtener detalles sobre cómo configurar correctamente un webhook entrante y qué estructura debe tener la plantilla JSON, consulta la guía oficial de Microsoft.

Vista de detalle

Al seleccionar un webhook desde la tabla se accede a su vista de detalle:

Visión general
Métricas

Visión general

Presenta tarjetas con información básica: Estado, Creado en y Actualizado en.

1. Visión general

Nombre. Nombre asignado al webhook.
Tipo de evento. Evento que activará el webhook.
Creado por. Usuario que creó el evento.
Actualizado por. Último usuario que modificó el webhook.
URL de destino. Dirección del sistema externo que recibe el evento y actúa según la información proporcionada en el mensaje.

2. Recursos seleccionados

Muestra los recursos asociados según el tipo de evento.

3. Plantilla de mensaje

Presenta la estructura JSON configurada para el webhook.

Métricas

Intentos de entrega de mensajes

Esta pestaña presenta dos niveles de información. En la parte superior, se muestran tarjetas resumen con el estado global de los mensajes enviados mediante el webhook:

Mensajes exitosos
Mensajes pendientes
Mensajes en progreso
Mensajes fallidos
Total de mensajes
Índice de éxito

En la parte inferior se muestra una tabla con el histórico de intentos de envío de mensajes correspondientes a los últimos 28 días. Los registros pueden filtrarse según los siguientes criterios: Todos los intentos, Intentos exitosos, Intentos pendientes, Intentos fallidos e Intentos en progreso. La tabla incluye la siguiente información:

Estado. Resultado de la ejecución.
Duración. En milisegundos, tiempo que tardó en ejecutarse el webhook.
Código de respuesta. Código HTTP devuelto al ejecutarse el webhook.
Ejecutado en. Fecha y hora en que se realizó la ejecución.
Acciones. Abre una ventana con el detalle de la ejecución.

Cuando una llamada a la URL de destino no se completa correctamente, el sistema reintenta el envío del mensaje de forma automática, según la siguiente programación:

Inmediatamente
A los 5 segundos
A los 5 minutos
A los 30 minutos
A las 2 horas
A las 5 horas
A las 10 horas
A las 10 horas (adicionales)

Cada intervalo se inicia a partir del fallo del intento anterior.

Si el envío de un mensaje falla tres veces y se completa con éxito en el cuarto intento, en la tabla se mostrarán cuatro intentos (tres fallidos y uno exitoso). No obstante, el sistema lo contabilizará como un único mensaje.

Acciones sobre webhooks

La vista de detalle también permite realizar las siguientes acciones sobre el webhook:

Habilitar / Deshabilitar

Habilita o deshabilita el webhook según su estado actual.

Los webhooks están deshabilitados por defecto.

Editar

Permite modificar:

Nombre
Tipo de evento
URL de destino
Recursos
Plantilla de mensaje

Eliminar

Elimina el webhook de forma permanente. Esta acción no se puede deshacer.

Probar

Envía un mensaje con el contenido de la plantilla a la URL configurada sin reemplazar las variables por valores reales. El objetivo de esta acción es validar la conectividad y el formato del mensaje.

​Vista general

​Crear una integración webhook

​Variables disponibles para el mensaje

​Todos los tipos de eventos

​Alerta activada

​Ejemplo de plantilla

​Microservicio ejecutado

​Ejemplo de plantilla

​Objeto creado, modificado o eliminado

​Ejemplo de plantilla

​Operación ejecutada

​Ejemplo de plantilla

​Operación ejecutada en un workspace

​Ejemplo de plantilla

​Slack

​Microsoft Teams

​Vista de detalle

​Visión general

​1. Visión general

​2. Recursos seleccionados

​3. Plantilla de mensaje

​Métricas

​Intentos de entrega de mensajes

​Acciones sobre webhooks

​Habilitar / Deshabilitar

​Editar

​Eliminar

​Probar

Vista general

Crear una integración webhook

Variables disponibles para el mensaje

Todos los tipos de eventos

Alerta activada

Ejemplo de plantilla

Microservicio ejecutado

Ejemplo de plantilla

Objeto creado, modificado o eliminado

Ejemplo de plantilla

Operación ejecutada

Ejemplo de plantilla

Operación ejecutada en un workspace

Ejemplo de plantilla

Slack

Microsoft Teams

Vista de detalle

Visión general

1. Visión general

2. Recursos seleccionados

3. Plantilla de mensaje

Métricas

Intentos de entrega de mensajes

Acciones sobre webhooks

Habilitar / Deshabilitar

Editar

Eliminar

Probar