Version: Next

Webhooks

Webhooks es una funcionalidad que permite integrar Portal 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, Portal 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 que actúa según la información proporcionada en el mensaje.
Estado. Indica si el webhook está Habilitado o Deshabilitado.

webhook-intg

Crear una integración webhook

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

En Portal, 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 que 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.
  note
  - 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:
    
    1 notificación webhook de tipo Operación ejecutada.
    
    3 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.

warning

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/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/hora de inicio de la alerta (ISO 8601)
#alert_element	Elemento que disparó la alerta
#workspace_id	ID del dispositivo
#workspace_name	Nombre del dispositivo
#workspace_last_user	Último usuario que usó el dispositivo
#workspace_reporting_group_id	ID del grupo de reporte
#workspace_reporting_group_name	Nombre del grupo de reporte

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/hora de inicio de la operación (ISO 8601)
#operation_enddate	Fecha/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 dispositivo
#workspace_name	Nombre del dispositivo
#workspace_last_user	Último usuario que usó el dispositivo
#workspace_reporting_group_id	ID del grupo de reporte
#workspace_reporting_group_name	Nombre del grupo de reporte

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/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/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/hora de creación de la operación (ISO 8601)
#started_at	Fecha/hora de inicio de la operación (ISO 8601)
#finished_at	Fecha/hora de finalización de la operación (ISO 8601)
#total_workspaces	Número total de dispositivos 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/hora de inicio de Flexxible Remote Assistance (FRA) (ISO 8601)
#fra_end	Fecha/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/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/hora de creación de la operación (ISO 8601)
#started_at	Fecha/hora de inicio de la operación (ISO 8601)
#finished_at	Fecha/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/hora de inicio de Flexxible Remote Assistance (FRA)(ISO 8601)
#operation_fra_end	Fecha/hora de fin de Flexxible Remote Assistance (FRA) (ISO 8601)
#workspace_id	ID del dispositivo
#workspace_name	Nombre del dispositivo
#workspace_last_user	Último usuario que usó el dispositivo
#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 dispositivo
#workspace_operation_startdate	Fecha/hora de inicio de la operación en el workspace (ISO 8601)
#workspace_operation_enddate	Fecha/hora de finalización de la operación en el workspace (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": "#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 Portal:

{
  "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"
        }
      ]
    }
  ]
}

note

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.

note

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.

webhook-detail1

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 que 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

Historial de ejecución

Muestra un registro de todas las activaciones webhook. El listado permite filtrar por: Todos los estados, Éxito, Pendiente, Erróneos y Enviando.

La tabla permite ver 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 resultado al ejecutarse el webhook.
Ejecutado en. Fecha y hora de la ejecución.
Acciones. Abre una ventana con el detalle de la ejecución del webhook.

Acciones sobre webhooks

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

webhook-actions

Habilitar / Deshabilitar

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

note

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​

Historial de ejecución​

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

Historial de ejecución

Acciones sobre webhooks

Habilitar / Deshabilitar

Editar

Eliminar

Probar