Webhooks

Settings › Web Hooks define solicitudes HTTP, con método, URL, encabezados y un cuerpo JSON con variables, que una plantilla de alerta envía cuando una alerta se genera o se resuelve.

Qué es y cuándo usarlo

Un webhook es una solicitud HTTP que SONAR envía a otro sistema cuando una alerta se genera o se resuelve: un mensaje en un canal de chat, un ticket en su mesa de ayuda, un evento en su plataforma de monitorización. La solicitud se define una vez en Admin Center › Settings › Web Hooks, con variables para la alerta, el dispositivo, el cliente y el sitio, y luego se elige en una plantilla de alerta como acción de fallo, acción de resolución, o ambas.

Use un webhook cuando su equipo no trabaja en el correo ni en los SMS, o cuando otro sistema debe registrar la alerta.

A diferencia de una acción de URL, que abre su navegador, un webhook lo envía directamente SONAR. Vea Acciones de URL para la diferencia.

Antes de empezar

• Para listar los webhooks y probarlos, su rol necesita Run URL Actions (grupo System en Admin Center › Roles). El mismo permiso rellena las listas de webhooks del formulario de la plantilla de alerta.

• Para añadirlos, editarlos o eliminarlos, su rol también necesita View Core Settings y Edit Core Settings (grupo Settings).

• Para asociar un webhook a una plantilla de alerta, su rol necesita Manage Alert Templates (grupo Alerts).

• El destino debe aceptar solicitudes desde SONAR. Si filtra por dirección de origen, pida al soporte de implementación de DataDike la dirección desde la que envía SONAR.

• La URL de destino, el método que espera y los encabezados que necesita, como un token de autorización emitido por ese sistema.

Pasos

Añadir un webhook

1. Abra Admin Center › Settings y la pestaña Web Hooks.

2. Haga clic en Add Web Hook.

3. Escriba un Name y, si lo desea, una Description.

4. Escriba el URL Pattern, la dirección a la que va la solicitud. Puede contener variables.

5. Elija el Method: GET, POST, PUT, DELETE o PATCH.

6. En Request Body, escriba el cuerpo JSON, con las variables dentro de las cadenas. La pestaña no está disponible para GET y DELETE.

7. En Request Headers, escriba los encabezados como un objeto JSON.

8. Haga clic en Test para probar la solicitud; vea más abajo.

9. Haga clic en Submit.

Un cuerpo para un servicio de chat podría ser así:

{
  "text": "{{alert.severity}} on {{agent.hostname}} ({{client.name}} / {{site.name}}): {{alert.message}}"
}

y los encabezados así, con el token emitido por ese servicio guardado en el almacén de claves:

{
  "Content-Type": "application/json",
  "Authorization": "Bearer {{global.CHAT_TOKEN}}"
}

Probar un webhook

1. En Add Web Hook o Edit Web Hook, haga clic en Test.

2. En Testing NAME, elija contra qué ejecutarlo: Agent, Site, Client o None, y seleccione el dispositivo, el sitio o el cliente.

3. Haga clic en Run.

SONAR envía la solicitud y muestra la URL y el Body que envió, con las variables rellenadas, y la Response que recibió. Con None, no se rellena ninguna variable. Las variables {{alert...}} solo reciben valor cuando el webhook se ejecuta para una alerta real.

Usarlo en una plantilla de alerta

1. Abra la plantilla de alerta; vea Alertas y plantillas de alerta.

2. En el paso Alert Actions, en Alert Failure Settings, elija Send a Web Hook y seleccione el webhook en Failure Web Hook.

3. En Alert Resolved Settings, elija Send a Web Hook y seleccione el webhook en Resolved Web Hook, si el otro sistema también debe saber que la alerta terminó.

4. En Run actions only on, deje activados los tipos de alerta que deben enviarlo: Agents (dispositivo con retraso), Checks, Tasks.

5. Guarde la plantilla.

Qué debe ver

El recuadro Web Hooks for Alert Failure/Resolved Actions lista cada webhook con su Name, su Description y su URL Pattern; si no hay ninguno, indica No Web Hooks added yet.

Para cada alerta de un dispositivo que usa la plantilla, SONAR envía el webhook de fallo una vez, cuando se genera la alerta, y el webhook de resolución una vez, cuando la alerta se resuelve por sí sola porque el check, la tarea o el dispositivo ha vuelto a la normalidad. Resolver una alerta a mano en Alerts no envía el webhook de resolución.

Las alertas informativas y de advertencia solo envían webhooks si Informational Alerts y Warning Alerts están marcadas en Admin Center › Settings › General; vea Configuración general.

Cómo verificar que funcionó

1. Haga clic en Test, ejecútelo contra un dispositivo de prueba y compruebe que Response contiene la respuesta que espera del otro sistema, y que el mensaje, el ticket o el evento aparece allí.

2. Haga fallar un check en un dispositivo de prueba cuya plantilla de alerta envía el webhook.

3. Abra Alerts, busque la alerta y haga clic en el botón Show failure action run results. El resultado muestra el código de estado HTTP que devolvió el otro sistema y su respuesta.

4. Las pruebas aparecen en Reports & Audits › Audits con la acción URL Action; vea Registro de auditoría.

Errores comunes

Síntoma	Causa	Solución
Response indica un error de conexión	URL incorrecta, o el destino no acepta solicitudes desde SONAR	Revise la URL; pida al soporte de implementación de DataDike la dirección desde la que envía SONAR
Response contiene un error de autenticación del otro sistema	Falta un encabezado o su token es incorrecto	Revise Request Headers, y el valor del almacén de claves si el token se guarda allí
El otro sistema rechaza el cuerpo	El cuerpo no es un JSON válido, o no tiene el formato que espera ese sistema	Corrija el JSON y compárelo con la documentación del otro sistema
Aparece None en la URL o en el cuerpo	No se pudo resolver una variable: está mal escrita, o es un campo personalizado o una clave que no existe	Revise los nombres de las variables; vea Variables de script
Failed to save con un mensaje sobre un campo en blanco	Name o URL Pattern está vacío	Rellene ambos
Failed to load actions, o la lista Failure Web Hook está vacía	El rol no tiene Run URL Actions	Conceda ese permiso en Admin Center › Roles
La prueba funciona pero las alertas no envían nada	La plantilla no se aplica al dispositivo, el tipo de alerta está desactivado en Run actions only on, o la severidad de la alerta está desactivada en Admin Center › Settings › General	Revise los tres puntos; vea Alertas y plantillas de alerta

Referencia de campos

Webhook

Campo	Qué hace	Valores aceptados	Valor por defecto
Name	Etiqueta en la lista y en la plantilla de alerta	Texto. Obligatorio	Vacío
Description	Nota para los demás administradores	Texto	Vacío
URL Pattern	Dirección a la que va la solicitud	Una URL completa, con variables si hace falta. Obligatorio	Vacío
Method	Método HTTP	GET, POST, PUT, DELETE, PATCH	POST
Request Body	Cuerpo de la solicitud, enviado como JSON	Un documento JSON. No se usa con GET y DELETE	{ }
Request Headers	Encabezados de la solicitud	Un objeto JSON con nombres y valores de encabezados	{"Content-Type": "application/json"}

Para POST, PUT y PATCH, SONAR espera la respuesta hasta 8 segundos.

Variables

Variable	Se sustituye por
{{alert.message}}	El mensaje de la alerta, que nombra el dispositivo y el check o la tarea que falló
{{alert.severity}}	error, warning o info
{{alert.alert_type}}	El tipo de alerta: availability (dispositivo con retraso), check o task
{{alert.alert_time}}	Cuándo se generó la alerta
{{alert.resolved_on}}	Cuándo se resolvió la alerta, para el webhook de resolución
{{agent.hostname}}	El nombre del dispositivo
{{client.name}}, {{site.name}}	El cliente y el sitio a los que pertenece el dispositivo
{{agent.FIELD}}, {{client.FIELD}}, {{site.FIELD}}	El valor del campo personalizado llamado FIELD; vea Campos personalizados
{{global.NAME}}	El valor de la clave NAME; vea Almacén de claves

La lista completa está en Variables de script.

Páginas relacionadas

• Alertas y plantillas de alerta: donde se asocian los webhooks

• Acciones de URL: enlaces que abre su navegador

• Almacén de claves: mantener los tokens fuera del propio webhook

• Notificaciones por correo electrónico y SMS: los demás canales de notificación

• Variables de script: todas las variables que puede usar