Puede configurar Atlas para enviar notificaciones de alerta a un punto final de webhook como solicitudes de publicación HTTP para procesamiento programático. Los webhooks le permiten integrar las alertas de Atlas con sistemas de supervisión personalizados, plataformas de gestión de incidentes o flujos de trabajo de automatización.
Acceso requerido
Para integrar Atlas con webhooks, debe tener acceso Organization Owner o Project Owner al proyecto.
Configurar una integración de Webhook
En Atlas, diríjase a la página Project Settings.
Si aún no se muestra, seleccione la organización que contiene su proyecto deseado en el menú Organizations de la barra de navegación.
Si aún no aparece, selecciona el proyecto deseado en el menú Projects de la barra de navegación.
En la barra lateral, haz clic en el icono junto a Project Overview.
La página Configuración del proyecto se muestra.
En Atlas, diríjase a la página Project Integrations.
Haz clic en la pestaña Integrations.
La página de Integraciones del proyecto se muestra.
(Opcional) Personalice las plantillas de webhook.
Puede personalizar los encabezados de solicitud y el contenido del cuerpo mediante plantillas FreeMarker:
En el campo Webhook Headers Template, introduzca una plantilla de FreeMarker para personalizar los encabezados HTTP enviados con las solicitudes de webhook.
En el campo Webhook Body Template, introduzca una plantilla de FreeMarker para personalizar la estructura del cuerpo de la solicitud.
Si configura plantillas y luego ve o edita la integración de webhook, las plantillas aparecen redactadas con ******. Puede sobrescribir las plantillas redactadas con nuevos valores.
Atlas valida la sintaxis de FreeMarker cuando guarda la configuración. Si su plantilla contiene sintaxis no válida, el formulario muestra un error de validación en línea.
Haz clic Saveen.
Para enviar alertas a su webhook, configure las notificaciones de alerta. Para obtener más información, consulte Configurar ajustes de alerta.
Encabezados de solicitud
Atlas incluye los siguientes encabezados HTTP con cada solicitud de webhook:
Encabezado | Descripción |
|---|---|
| Indica el estado de la alerta. Valores posibles:
|
| (Opcional) Si especifica un secreto en el campo Webhook Secret, Atlas incluye este encabezado. Contiene la firma Base64-codificada HMAC-SHA-1 del cuerpo de la solicitud. Atlas crea la firma utilizando el secreto proporcionado. Utilice este encabezado para verificar que la solicitud de webhook se originó en Atlas. |
Cuerpo de la solicitud
El cuerpo de la solicitud contiene un documento JSON que utiliza el mismo formato que el recurso de alertas de la Atlas Administration API. La carga útil incluye campos clave como:
id: Identificador único para la alerta.eventTypeName: Tipo de evento que activó la alerta.created: Marca de tiempo en que se creó la alerta.status: Estado actual de la alerta (p. ej.,OPEN,CLOSED).humanReadable: Descripción legible por humanos de la alerta. Este campo contiene el nombre del proyecto y el nombre de la organización en el formato "Proyecto: [nombre del proyecto] Organización: [nombre de la organización]" junto con otros detalles de la alerta.
Para obtener una lista completa de los campos, consulte la documentación de Atlas Administration API Obtener todas las alertas del proyecto.
Carga útil de webhook de ejemplo
El siguiente ejemplo muestra una carga útil de webhook de muestra para una alerta de espacio en disco:
{ "id": "5d1b6f8e8c2e4e2d3c4a5b6c", "groupId": "5d1b6f8e8c2e4e2d3c4a5b6d", "eventTypeName": "OUTSIDE_METRIC_THRESHOLD", "status": "OPEN", "created": "2024-01-15T10:30:00Z", "updated": "2024-01-15T10:30:00Z", "lastNotified": "2024-01-15T10:30:00Z", "humanReadable": "Disk space used on data partition is 95.2%. Project: MyProject Organization: MyOrganization", "metricName": "DISK_PARTITION_SPACE_USED_DATA", "currentValue": { "number": 95.2, "units": "RAW" } }
Autenticar solicitudes de webhook
El campo Webhook Secret almacena un secreto que Atlas utiliza únicamente para generar el encabezado X-MMS-Signature para la verificación de solicitudes. Atlas no envía el secreto directamente como encabezado de autenticación o Bearer token.
Si el punto de conexión del webhook requiere autenticación, debe gestionarlo de forma independiente mediante uno de los siguientes métodos:
Parámetros de query: incluya las credenciales de autenticación en el Webhook URL como parámetros de query. Por ejemplo:
https://example.com/webhook?token=your-auth-tokenLista de acceso IP: configure el punto de conexión del webhook para aceptar solicitudes solo de direcciones IP de Atlas. Esta configuración garantiza que solo Atlas pueda enviar solicitudes a su punto de conexión.
Proxy inverso o API Gateway: utilice un proxy inverso o una API Gateway que gestione la autenticación antes de reenviar las solicitudes a su punto final de webhook.
Verificar solicitudes de webhook
Para verificar que una solicitud de webhook se originó en Atlas, valide el encabezado X-MMS-Signature:
Limitaciones
Cuando utilice integraciones de webhook, considere las siguientes limitaciones:
Gravedad de la alerta no incluida
La carga útil del webhook no incluye el nivel de gravedad de la alerta que configura en Atlas. Para recuperar la gravedad configurada, realice una llamada adicional al punto de conexión Obtener una configuración de alerta de la Atlas Administration API utilizando el alertConfigId de la carga útil del webhook.
Sin alertas de prueba manual
Atlas no proporciona una forma de activar alertas de prueba manualmente. Para probar su punto de conexión de webhook, puede configurar temporalmente una alerta con condiciones fáciles de activar, como:
Un umbral de espacio en disco bajo en un clúster de prueba.
Un umbral de recuento de conexiones que puede activar abriendo varias conexiones.
Un umbral de atraso de la replicación en un set de réplicas de prueba.
Después de confirmar que su webhook recibe las alertas correctamente, puede borrar la configuración de alerta de prueba.
Configuración del Firewall
Si su firewall requiere que configure una lista de acceso IP, permita el acceso desde direcciones IP de Atlas para que Atlas pueda comunicarse con su punto final de webhook.
Solucionar problemas de entrega de webhooks
Si su webhook no recibe alertas: