webhook

Descripción general

El tipo de medio webhook es útil para realizar llamadas HTTP utilizando código JavaScript personalizado para una integración sencilla con software externo como sistemas de helpdesk, chats o mensajería. Puede optar por importar una integración proporcionada por Zabbix o crear una integración personalizada desde cero.

Integraciones

Las siguientes integraciones están disponibles y permiten usar tipos de medio webhook predefinidos para enviar notificaciones de Zabbix a:

Además de los servicios enumerados aquí, Zabbix puede integrarse con Spiceworks (no se requiere webhook). Para convertir las notificaciones de Zabbix en tickets de Spiceworks, cree un tipo de medio de correo electrónico e introduzca la dirección de correo electrónico del servicio de asistencia de Spiceworks (por ejemplo, [email protected]) en la configuración de perfil de un usuario de Zabbix designado.

Configuración

Para comenzar a utilizar una integración de webhook:

  1. Localice el archivo .yaml requerido en el directorio templates/media de la versión de Zabbix descargada o descárguelo del repositorio git de Zabbix.
  2. Importe el archivo en su instalación de Zabbix. El webhook aparecerá en la lista de tipos de medios.
  3. Configure el webhook según las instrucciones del archivo Readme.md (puede hacer clic en el nombre de un webhook más arriba para acceder rápidamente a Readme.md).

Para crear un webhook personalizado desde cero:

  1. Vaya a Alertas > Tipos de medios.
  2. Haga clic en Crear tipo de medio.
  3. Introduzca los parámetros del tipo de medio webhook en el formulario.

La pestaña Tipo de medio contiene varios atributos específicos de este tipo de medio:

Todos los campos de entrada obligatorios están marcados con un asterisco rojo.

Los siguientes parámetros son específicos del tipo de medio webhook:

Parámetro Descripción
Parámetros Especifique las variables del webhook como pares de atributo y valor.
En los webhooks preconfigurados, la lista de parámetros varía según el servicio. Consulte el archivo Readme.md del webhook para obtener la descripción de los parámetros.
En los webhooks nuevos, se incluyen varias variables comunes de forma predeterminada (URL:<empty>, HTTPProxy:<empty>, To:{ALERT.SENDTO}, Subject:{ALERT.SUBJECT}, Message:{ALERT.MESSAGE}); puede conservarlas o eliminarlas.

Los parámetros del webhook admiten macros de usuario, todas las macros compatibles con las notificaciones de problemas y, adicionalmente, las macros {ALERT.SENDTO}, {ALERT.SUBJECT} y {ALERT.MESSAGE}.

Si especifica un proxy HTTP, el campo admite la misma funcionalidad que el campo proxy HTTP de la configuración del item. La cadena del proxy puede llevar el prefijo [scheme]:// para especificar el tipo de proxy utilizado (por ejemplo, https, socks4, socks5; consulte la documentación).
Script Introduzca el código JavaScript en el editor modal que se abre al hacer clic en el campo del parámetro o en el icono del lápiz situado junto a él. Este código realizará la operación del webhook.
El script es un código de función que acepta pares de parámetro y valor. Los valores deben convertirse en objetos JSON mediante el método JSON.parse(), por ejemplo: var params = JSON.parse(value);.

El código tiene acceso a todos los parámetros, puede realizar solicitudes HTTP GET, POST, PUT y DELETE, admitir métodos adicionales como CONNECT, PATCH, HEAD, OPTIONS y TRACE, y controlar las cabeceras HTTP y el cuerpo de la solicitud.
El script debe contener un operador return; de lo contrario, no será válido. Puede devolver un estado OK junto con una lista opcional de etiquetas y valores de etiquetas (consulte la opción Procesar etiquetas) o una cadena de error.

Los eventos de recuperación (generados automáticamente o como resultado de un cierre manual) son creados por el server e incluyen las etiquetas del evento resuelto (incluidas las etiquetas heredadas de templates, hosts y triggers). Los scripts de webhook se ejecutan después de crear la alerta; por lo tanto, las etiquetas devueltas por un script de webhook se añaden únicamente después de la creación inicial de la alerta y no estarán presentes en las macros {EVENT.TAGS} y {EVENT.RECOVERY.TAGS} del mensaje inicial del problema ni del mensaje de recuperación inmediato.
Nota: Se recomienda utilizar variables locales (por ejemplo, var local = 1) en lugar de variables globales (por ejemplo, global = 1) para garantizar que cada script opere con sus propios datos y evitar colisiones entre llamadas simultáneas (consulte los problemas conocidos).

Consulte también: Directrices para el desarrollo de webhooks, Ejemplos de scripts de webhook, Objetos JavaScript adicionales.
Tiempo de espera Tiempo de espera de ejecución de JavaScript (1-60 s, valor predeterminado: 30 s).
Se admiten sufijos de tiempo (por ejemplo, 30s, 1m).
Procesar etiquetas Marque la casilla para procesar los valores de las propiedades JSON devueltas como etiquetas. Estas etiquetas se añaden a las etiquetas de problemas existentes.
Tenga en cuenta que, al utilizar etiquetas de webhook, el webhook debe devolver un objeto JSON que contenga al menos un objeto de etiquetas vacío: var result = {tags: {}};
Ejemplos de etiquetas que se pueden devolver: jira-id:prod-1234, responsible:John Smith, processed:<no value>
Incluir entrada en el menú de eventos Marque la casilla para incluir una entrada en el menú de eventos que enlace con un ticket externo creado.
Se incluirá una entrada para cada webhook que esté habilitado y tenga marcada esta casilla. Tenga en cuenta que, si los parámetros Nombre de la entrada del menú y URL de la entrada del menú contienen macros {EVENT.TAGS.<tag name>}, se incluirá una entrada únicamente si estas macros se pueden resolver (es decir, si el evento tiene definidas estas etiquetas).
Si se marca, el webhook no debe utilizarse para enviar notificaciones a distintos usuarios (considere la posibilidad de crear un usuario dedicado) y no debe utilizarse en varias acciones de alerta para un único evento de problema.
Nombre de la entrada del menú Especifique el nombre de la entrada del menú.
Se admite la macro {EVENT.TAGS.<tag name>}.
Este campo solo es obligatorio si se marca Incluir entrada en el menú de eventos.
URL de la entrada del menú Especifique la URL subyacente de la entrada del menú.
Se admite la macro {EVENT.TAGS.<tag name>}.
Este campo solo es obligatorio si se marca Incluir entrada en el menú de eventos.

Consulte parámetros comunes de los tipos de medios para obtener información detallada sobre cómo configurar los mensajes predeterminados y las opciones de procesamiento de alertas.

Aunque un webhook no utilice mensajes predeterminados, las plantillas de mensajes para los tipos de operación utilizados por este webhook deben seguir estando definidas.

Pruebas

Para probar un tipo de medio webhook configurado:

  1. Localice el webhook correspondiente en la lista de tipos de medio.
  2. Haga clic en Probar en la última columna de la lista (se abrirá una ventana de prueba).
  3. Edite los valores de los parámetros del webhook según sea necesario.
    Reemplace las macros por valores de ejemplo; de lo contrario, las macros no se resolverán y la prueba fallará.
  4. Haga clic en Probar.

Reemplazar o eliminar valores en la ventana de prueba solo afecta al procedimiento de prueba; los valores reales de los atributos del webhook permanecerán sin cambios.

Para ver las entradas del registro de pruebas del tipo de medio sin salir de la ventana de prueba, haga clic en Abrir registro (se abrirá una nueva ventana emergente).

Si la prueba del webhook es exitosa:

  • Se muestra el mensaje "Prueba de tipo de medio exitosa.".
  • La respuesta del servidor aparece en el campo gris Respuesta.
  • El tipo de respuesta (JSON o Cadena) se especifica debajo del campo Respuesta.

Si la prueba del webhook falla:

  • Se muestra el mensaje "La prueba del tipo de medio falló.", seguido de detalles adicionales sobre el fallo.

Medios del usuario

Una vez configurado el tipo de medio, vaya a la sección Usuarios > Usuarios y asigne el medio webhook a un usuario existente o cree un usuario nuevo que represente al webhook. Los pasos para configurar los medios de usuario para un usuario existente, que son comunes a todos los tipos de medios, se describen en la página Tipos de medios.

Si un webhook utiliza etiquetas para almacenar el ID del ticket\mensaje, evite asignar el mismo webhook como medio a diferentes usuarios, ya que esto puede provocar errores del webhook (se aplica a la mayoría de los webhooks que utilizan la opción Incluir entrada en el menú de eventos). En este caso, la práctica recomendada es crear un usuario dedicado que represente al webhook:

  1. Después de configurar el tipo de medio webhook, vaya a la sección Usuarios > Usuarios y cree un usuario de Zabbix dedicado para representar al webhook; por ejemplo, con el nombre de usuario Slack para el webhook de Slack. Todos los ajustes, excepto los medios, pueden dejarse con sus valores predeterminados, ya que este usuario no iniciará sesión en Zabbix.
  2. En el perfil del usuario, vaya a la pestaña Medios y añada un webhook con la información de contacto necesaria. Si el webhook no utiliza un campo Enviar a, introduzca cualquier combinación de caracteres compatibles para omitir los requisitos de validación.
  3. Conceda a este usuario al menos permisos de lectura para todos los hosts para los que deba enviar alertas.

Al configurar la acción de alerta, añada este usuario en el campo Enviar a usuarios de los detalles de la operación; esto indicará a Zabbix que utilice el webhook para las notificaciones de esta acción.

Configuración de acciones de alerta

Las acciones determinan qué notificaciones deben enviarse a través del webhook. Los pasos para configurar acciones que implican webhooks son los mismos que para todos los demás tipos de medios, con estas excepciones:

  • Si un webhook usa etiquetas de webhook para almacenar el ID de ticket\mensaje y gestionar las operaciones de actualización\resolución, evite usar el mismo webhook en varias acciones de alerta para un único evento de problema. Si {EVENT.TAGS.<tag name>} existe y se actualiza en el webhook, su valor resultante no estará definido. Para evitar esto, use un nuevo nombre de etiqueta en el webhook para almacenar los valores actualizados. Esto se aplica a los webhooks de Jira, Jira Service Desk, Mattermost, Opsgenie, OTRS, Redmine, ServiceNow, Slack, Zammad y Zendesk proporcionados por Zabbix, así como a la mayoría de los webhooks que utilizan la opción Include event menu entry. Tenga en cuenta, sin embargo, que un único webhook puede usarse en varias operaciones o pasos de escalado de la misma acción, así como en diferentes acciones que no se activarán por el mismo evento de problema debido a diferentes condiciones.
  • Al usar un webhook en acciones para eventos internos, asegúrese de marcar la casilla Custom message y definir un mensaje personalizado en la configuración de la operación de la acción. De lo contrario, no se enviará ninguna notificación.