Puede configurar Cloud Manager para enviar notificaciones de alerta a un punto final de webhook como solicitudes HTTP de publicación para procesamiento programático. Los webhooks le permiten integrar las alertas de Cloud Manager con sistemas de supervisión personalizados, plataformas de gestión de incidentes o flujos de trabajo de automatización.
Acceso requerido
Para integrar Cloud Manager con webhooks, se 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 con 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 añade el encabezado de solicitud X-MMS-Signature. Este encabezado contiene la firma HMAC-SHA-1 codificada en base64del cuerpo de la solicitud. 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 de alertas de la Cloud Manager 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 (por ejemplo,OPEN,CLOSED).humanReadable: descripción legible por personas de la alerta.
Para obtener una lista completa de los campos, consulte la documentación del endpoint Get One Alerta.
Carga útil de webhook de ejemplo
El siguiente ejemplo muestra una carga útil de webhook de muestra para una alerta de umbral de métricas:
{ "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" }}Personalizar 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 renderizado debe ser válido JSON y se envía con la cabecera Content-Type: application/json. Los encabezados renderizados deben formar un objeto JSON que asigna 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, supera el límite de tamaño o produce una salida no válida, Cloud Manager envía en su lugar su carga útil y encabezados por defecto y aún 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 exclusivamente para generar el encabezado X-MMS-Signature para la verificación de solicitudes. Cloud Manager 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 su extremo webhook para aceptar solicitudes únicamente de Cloud Manager direcciones IP. 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, haga una llamada adicional al punto de conexión Get One alerta Configuration utilizando el alertConfigId de la carga útil del webhook.
Sin alertas de prueba manual
Cloud Manager no proporciona una forma de activador alertas de prueba manualmente. Para probar su punto final de webhook, puede configurar temporalmente una alerta con condiciones que permitan un activador fácil, como:
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 cortafuegos le exige configurar 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: