Documentation
Table of Contents
4 Webhook
Visi¨®n general
El tipo de medio de webhook es ¨²til para realizar llamadas HTTP utilizando C¨®digo JavaScript para una integraci¨®n sencilla con software externo como sistemas de mesa de ayuda, chats o mensajeros. Puede optar por importar una integraci¨®n proporcionada por Áú»¢¶Ä²© o crear una integraci¨®n personalizada desde rascar.
Integraciones
Las siguientes integraciones est¨¢n disponibles y permiten usar tipos de medios de webhook predefinidos para enviar notificaciones de Áú»¢¶Ä²© a:
Adem¨¢s de los servicios enumerados aqu¨ª, Áú»¢¶Ä²© se puede integrar con Spiceworks (no se requiere webhook). Para convertir las notificaciones de Áú»¢¶Ä²© en tickets de Spiceworks, cree un tipo de medio de correo electr¨®nico e ingrese la direcci¨®n de correo electr¨®nico del servicio de asistencia t¨¦cnica de Spiceworks (p. ej., [email protected]) en la configuraci¨®n del perfil de un usuario de Áú»¢¶Ä²© designado.
°ä´Ç²Ô´Ú¾±²µ³Ü°ù²¹³¦¾±¨®²Ô
Para comenzar a utilizar una integraci¨®n de webhook:
- Localice el archivo .xml requerido en el directorio
templates/mediade la versi¨®n descargada de Áú»¢¶Ä²© o desc¨¢rguelo desde el de Áú»¢¶Ä²©. - Importe el archivo en su instalaci¨®n de Áú»¢¶Ä²©. El webhook aparecer¨¢ en la lista de tipos de medios.
- Configure el webhook de acuerdo con las instrucciones del archivo Readme.md (puede hacer clic en el nombre de un webhook arriba para acceder r¨¢pidamente a Readme.md).
Para crear un webhook personalizado desde cero:
- Vaya a Alertas ¡ú Tipos de medios.
- Haga clic en Crear tipo de medio.
La pesta?a Tipo de medio contiene varios atributos espec¨ªficos para este tipo de medio:
Todos los campos de entrada obligatorios est¨¢n marcados con un asterisco rojo.
Los siguientes par¨¢metros son espec¨ªficos para el tipo de medio de webhook:
| ±Ê²¹°ù¨¢³¾±ð³Ù°ù´Ç | ¶Ù±ð²õ³¦°ù¾±±è³¦¾±¨®²Ô |
|---|---|
| ±Ê²¹°ù¨¢³¾±ð³Ù°ù´Çs | Especifique las variables del webhook como pares de atributo y valor. Para los webhooks preconfigurados, la lista de par¨¢metros var¨ªa seg¨²n el servicio. Consulte el archivo Readme.md del webhook para obtener una descripci¨®n de los par¨¢metros. Para los nuevos webhooks, 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 que se admiten en las notificaciones de problemas y, adem¨¢s, las macros {ALERT.SENDTO}, {ALERT.SUBJECT} y {ALERT.MESSAGE}. Si especifica un proxy HTTP, el campo admite la misma funcionalidad que en el campo de configuraci¨®n del elemento proxy HTTP. La cadena de proxy puede tener como prefijo [scheme]:// para especificar qu¨¦ tipo de proxy se utiliza (p. ej., https, calcetines4, calcetines5; consulte la ). |
| Script | Ingrese el c¨®digo JavaScript en el editor modal que se abre al hacer clic en el campo de par¨¢metros o en el ¨ªcono de l¨¢piz que se encuentra junto a ¨¦l. Este c¨®digo realizar¨¢ la operaci¨®n del webhook. El script es un c¨®digo de funci¨®n que acepta pares par¨¢metro-valor. Los valores se deben convertir en objetos JSON utilizando 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 y tiene control sobre los encabezados HTTP y el cuerpo de la solicitud. El script debe contener un operador de retorno, de lo contrario no ser¨¢ v¨¢lido. Puede devolver el estado OK junto con una lista opcional de etiquetas y valores de etiquetas (ver la opci¨®n Etiquetas de procesamiento) o una cadena de error. Tenga en cuenta que el script se ejecuta solo despu¨¦s de que se crea una alerta. Si el script est¨¢ configurado para devolver y procesar etiquetas, estas etiquetas no se resolver¨¢n en las macros {EVENT.TAGS} y {EVENT.RECOVERY.TAGS} en el mensaje de problema inicial y los mensajes de recuperaci¨®n porque el script a¨²n no tuvo tiempo de ejecutarse. Nota: Se recomienda usar variables locales en lugar de globales para asegurarse de que cada script funcione con sus propios datos y que no haya colisiones entre llamadas simult¨¢neas (consulte problemas conocidos). Consulte tambi¨¦n: Pautas de desarrollo de webhooks, Ejemplos de scripts de webhooks, JavaScript adicional, objetos](/manual/config/items/preprocessing/javascript/javascript_objects). |
| Tiempo de espera | Tiempo de espera de ejecuci¨®n de JavaScript (1-60 s, 30 s predeterminado). Se admiten sufijos de tiempo, p. ej., 30 s, 1 m. |
| Etiquetas de proceso | Marque la casilla de verificaci¨®n para procesar los valores de propiedad JSON devueltos como etiquetas. Estas etiquetas se agregan a cualquier etiqueta de problema existente. Tenga en cuenta que al usar 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 de verificaci¨®n para incluir una entrada en el men¨² de eventos que se vincule a un ticket externo creado. Se incluir¨¢ una entrada para cada webhook que est¨¦ habilitado y tenga esta casilla de verificaci¨®n marcada. Tenga en cuenta que si los par¨¢metros Nombre de entrada de men¨² y URL de entrada de men¨² contienen macros {EVENT.TAGS.<nombre de etiqueta>}, se incluir¨¢ una entrada solo si estas macros se pueden resolver (es decir, el evento tiene estas etiquetas definidas). Si est¨¢ marcado, el webhook no se debe utilizar para enviar notificaciones a diferentes usuarios (considere crear un usuario dedicado en su lugar) y no se debe utilizar en m¨²ltiples acciones de alerta para un solo evento de problema. |
| Nombre de la entrada del men¨² | Especifique el nombre de la entrada del men¨². Se admite la macro {EVENT.TAGS.<nombre de etiqueta>}. Este campo solo es obligatorio si est¨¢ marcada la opci¨®n Incluir entrada del men¨² de eventos. |
| URL de la entrada del men¨² | Especifique la URL subyacente de la entrada del men¨². Se admite la macro {EVENT.TAGS.<nombre de etiqueta>}. Este campo solo es obligatorio si est¨¢ marcada la opci¨®n Incluir entrada del men¨² de eventos. |
Consulte par¨¢metros de tipo de medio com¨²n para obtener detalles sobre c¨®mo configurar los mensajes predeterminados y las opciones de procesamiento de alertas.
Incluso si un webhook no utiliza mensajes predeterminados, deben definirse las plantillas de mensajes para los tipos de operaciones que utiliza este webhook.
Pruebas de tipo de medio
Para probar un tipo de medio de webhook configurado:
- Localice el webhook correspondiente en la lista de tipos de medios.
- Haga clic en Prueba en la ¨²ltima columna de la lista (una ventana de prueba abrir¨¢).
- Edite los valores de los par¨¢metros del webhook, si es necesario.
- Haga clic en Probar.
De forma predeterminada, las pruebas de webhook se realizan con par¨¢metros ingresados durante configuraci¨®n. Sin embargo, es posible cambiar los valores de los atributos para pruebas. Reemplazar o eliminar valores en la ventana de prueba afecta la S¨®lo durante el procedimiento de prueba, los valores reales de los atributos del webhook permanecer¨¢n sin alterar.
Para ver las entradas del registro de pruebas de 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 "Error en la prueba del tipo de medio.", seguido de detalles adicionales del error.
Medios de usuario
Una vez configurado el tipo de medio, vaya a la secci¨®n Usuarios ¡ú Usuarios y asigne los medios del webhook a un usuario existente o cree un nuevo usuario para representar el webhook. Lo pasos para configurar medios de usuario para un usuario existente, que son comunes para todos los tipos de medios, se describen en la p¨¢gina de tipos de medios.
Si un webhook utiliza etiquetas para almacenar el ID del ticket\mensaje, evite asignar el mismo webhook como medio para diferentes usuarios, ya que al hacerlo puede provocar errores en el webhook (se aplica a la mayor¨ªa de los webhooks que utilizan la opci¨®n Incluir evento entrada de men¨² ). En este caso, la mejor pr¨¢ctica es crear un usuario dedicado para representar el webhook:
- Despu¨¦s de configurar el tipo de medio del webhook, vaya a la secci¨®n Usuarios ¡ú Usuarios y cree un usuario de Áú»¢¶Ä²© dedicado para representar el webhook, por ejemplo, con un nombre de usuario Slack para Slack webhook. Todas las configuraciones, excepto los medios, se pueden dejar en sus valores predeterminados. ya que este usuario no iniciar¨¢ sesi¨®n en Áú»¢¶Ä²©.
- En el perfil de usuario, vaya a la pesta?a Medios y agregue un webhook con la informaci¨®n de contacto requerida. Si el webhook no utiliza un campo Enviar a, ingrese cualquier combinaci¨®n de caracteres admitidos para omitir los requisitos de validaci¨®n.
- Otorgue a este usuario al menos permisos de lectura a todos los equipos para los cuales debe enviar las alertas.
Al configurar la acci¨®n de alerta, agregue este usuario al campo Enviar a usuarios en Detalles de la operaci¨®n: esto le indicar¨¢ a Áú»¢¶Ä²© que use el webhook para notificaciones de esta acci¨®n.
°ä´Ç²Ô´Ú¾±²µ³Ü°ù²¹³¦¾±¨®²Ô de acciones de alerta
Las acciones determinan qu¨¦ notificaciones se deben enviar a trav¨¦s del webhook. Los pasos para configurar acciones que involucran 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 o mensaje y manejar operaciones de actualizaci¨®n o resoluci¨®n, evite usar el mismo webhook en m¨²ltiples acciones de alerta para un solo evento de problema. Si {EVENT.TAGS.<nombre de etiqueta>} 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 valores actualizados. Esto se aplica a los webhooks de Jira, Jira Service Desk, Mattermost, Opsgenie, OTRS, Redmine, ServiceNow, Slack, Zammad y Zendesk proporcionados por Áú»¢¶Ä²© y a la mayor¨ªa de los webhooks que utilizan la opci¨®n Incluir entrada de men¨² de evento. Sin embargo, tenga en cuenta que se puede utilizar un ¨²nico webhook en varias operaciones o pasos de escalamiento 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.
- Cuando utilice un webhook en acciones para eventos internos, aseg¨²rese de marcar la casilla de verificaci¨®n Mensaje personalizado y defina un mensaje personalizado en la configuraci¨®n de la operaci¨®n de la acci¨®n. De lo contrario, no se enviar¨¢ una notificaci¨®n.