Puedes configurar Cloud Manager para que envíe notificaciones de alerta a un punto final de webhook como solicitudes HTTP POST para su procesamiento programático. Los webhooks te permiten integrar las alertas de Cloud Manager con sistemas de monitorización personalizados, plataformas de gestión de incidentes o flujos de trabajo de automatización.
Acceso requerido
Para integrar Cloud Manager con webhooks, debe tener acceso Project Monitoring Admin al proyecto.
Configurar una integración de Webhook
En MongoDB Cloud Manager, ve 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, haga clic en Project Settings.
La página Configuración del proyecto se muestra.
Ir a la página Project Integrations.
En la barra lateral, haz clic en Integrations en la sección Settings.
La página de Integraciones del proyecto se muestra.
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
Cloud Manager incluye los siguientes encabezados HTTP en cada solicitud de webhook:
Cloud Manager agrega un encabezado de solicitud llamado X-MMS-Event para distinguir entre varios estados de alerta. Los valores posibles para este encabezado son:
| La alerta se acaba de abrir. |
| La alerta se resolvió. |
| Una alerta previamente abierta aún está abierta. |
| La alerta fue reconocida. |
| La alerta se volvió inválida y fue cancelada. |
| Representa una alerta informativa, que es un evento de punto en el tiempo, como "Primario Elegido." |
Si especifica una clave en el campo Webhook Secret, MongoDB Cloud Manager agrega el encabezado de solicitud X-MMS-Signature. Este encabezado contiene la firma HMAC-SHA-1 del cuerpo de la solicitud, codificada en base64. MongoDB Cloud Manager crea la firma utilizando el secreto proporcionado.
Cuerpo de la solicitud
El cuerpo de la solicitud contiene un documento JSON que utiliza el mismo formato que el recurso Alertas de la API de Cloud Manager. 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 (por ejemplo,OPEN,CLOSED).humanReadable: Descripción de la alerta legible para humanos.
Para obtener una lista completa de los campos, consulte la documentación del punto final de Get One Alert.
Carga útil de webhook de ejemplo
El siguiente ejemplo muestra una carga útil de webhook de muestra para una alerta de umbral de métrica:
{ "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%.", "metricName": "DISK_PARTITION_SPACE_USED_DATA", "currentValue": { "number": 95.2, "units": "RAW" } }
Personaliza las plantillas de webhook
Puede personalizar los encabezados de solicitud de webhook y el contenido del cuerpo configurando los campos webhookHeadersTemplate y webhookBodyTemplate en la notificación de webhook. Cada plantilla admite la interpolación ${field}: Cloud Manager reemplaza cada marcador de posición ${field} con el valor del campo coincidente del documento de alerta cuando envía la notificación.
Puede interpolar cualquier campo que devuelva el documento de alerta, como ${eventTypeName}, ${clusterName}, ${status} y ${created}. Para obtener la lista completa de campos que puede interpolar, consulte los campos de respuesta del punto final Obtener una alerta.
Por ejemplo, la plantilla de cuerpo {"event": "${eventTypeName}", "cluster": "${clusterName}"} renderiza cada marcador de posición con su valor de alerta antes de que Cloud Manager envíe la solicitud.
El cuerpo generado debe ser JSON válido y se envía con el encabezado Content-Type: application/json. Los encabezados generados deben formar un objeto JSON que asigne cada nombre de encabezado a su valor. Cloud Manager no expone el secreto del webhook ni el encabezado de firma a las plantillas, y oculta ambos campos de plantilla en las respuestas de la API.
Si una plantilla no se renderiza correctamente, supera el límite de tamaño o produce una salida no válida, Cloud Manager envía su carga útil y encabezados predeterminados y, aun así, entrega la notificación.
Para obtener una vista previa de la salida renderizada antes de guardar la alerta, haz clic en el botón Post test message to webhook, que renderiza tus plantillas con datos de alerta de muestra.
Autenticar solicitudes de webhook
El campo Webhook Secret almacena un secreto que Cloud Manager utiliza únicamente para generar el encabezado X-MMS-Signature para la verificación de la solicitud. Cloud Manager no envía el secreto directamente como encabezado de autenticación ni como token de portador.
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 su punto final de webhook para que solo acepte solicitudes de direcciones IP de Cloud Manager. Esta configuración garantiza que solo Cloud Manager pueda enviar solicitudes a su punto final.
Proxy inverso o puerta de enlace API: utilice un proxy inverso o una puerta de enlace API 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 Cloud Manager, 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 Cloud Manager. Para recuperar la gravedad configurada, realice una llamada adicional al punto final Get One Alert Configuration utilizando alertConfigId de la carga útil del webhook.
Sin alertas de prueba manual
Cloud Manager no ofrece una forma de activar alertas de prueba manualmente. Para probar su punto final de webhook, puede configurar temporalmente una alerta con condiciones fáciles de activar, como por ejemplo:
Un umbral bajo de espacio en disco en una implementación 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 las direcciones IP de Cloud Manager para que Cloud Manager pueda comunicarse con su punto final de webhook.
Solucionar problemas de entrega de webhooks
Si su webhook no recibe alertas: