Integração com webhooks no Cloud Manager

Acesso necessário

Para integrar o Cloud Manager aos webhooks, você deve ter acesso Project Monitoring Admin ao projeto.

Configurar uma integração de Webhook

Para enviar alertas para o seu webhook, configure as notificações de alerta. Para saber mais, consulte Definir configurações de alerta.

Cabeçalhos de solicitação

O Cloud Manager inclui os seguintes cabeçalhos HTTP com cada solicitação de webhook:

O Cloud Manager adiciona um cabeçalho de solicitação chamado X-MMS-Event para distinguir entre vários estados de alerta. Os valores possíveis para este cabeçalho são:

Se você especificar uma chave no campoWebhook Secret, o MongoDB Cloud Manager adicionará o cabeçalho de solicitação X-MMS-Signature. Esse cabeçalho contém a assinatura HMAC-SHA-1 codificada de base64 do corpo da solicitação. O MongoDB Cloud Manager cria a assinatura usando o segredo fornecido.

Corpo da solicitação

O corpo da solicitação contém um documento JSON que usa o mesmo formato que o recurso de alertas da API do Cloud Manager . A carga útil inclui campos principais, como:

• id: Identificador exclusivo para o alerta.

• eventTypeName: Tipo de evento que acionou o alerta.

• created: Carimbo de data/hora quando o alerta foi criado.

• status: status atual do alerta (por exemplo, OPEN, CLOSED).

• humanReadable: Descrição legível por humanos do alerta.

Para obter uma lista completa de campos, consulte a documentação do endpoint Get One Alert.

{
  "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 modelos de webhook

Você pode personalizar os cabeçalhos de solicitação do webhook e o conteúdo do corpo definindo os campos webhookHeadersTemplate e webhookBodyTemplate na notificação do webhook. Cada modelo suporta interpolação ${field}: o Cloud Manager substitui cada espaço reservado ${field} pelo valor do campo correspondente do documento de alerta quando envia a notificação.

Você pode interpolar qualquer campo que o documento de alerta retorne, como ${eventTypeName}, ${clusterName}, ${status} e ${created}. Para obter a lista completa de campos que você pode interpolar, consulte os campos de resposta para o ponto de extremidade Obter um alerta.

Por exemplo, o modelo de corpo {"event": "${eventTypeName}", "cluster": "${clusterName}"} renderiza cada espaço reservado com seu valor de alerta antes que o Cloud Manager envie a solicitação.

O corpo renderizado deve ser JSON válido e é enviado com o cabeçalho Content-Type: application/json. Os cabeçalhos renderizados devem formar um objeto JSON que mapeie cada nome de cabeçalho para seu valor. O Cloud Manager não expõe o segredo do webhook ou o cabeçalho de assinatura a modelos e edita ambos os campos de modelo nas respostas da API.

Se um modelo falhar ao renderizar, exceder o limite de tamanho ou produzir uma saída inválida, o Cloud Manager enviará sua carga útil e cabeçalhos padrão e ainda entregará a notificação.

Para visualizar a saída renderizada antes de salvar o alerta, clique no botão Post test message to webhook, que renderiza seus modelos em relação aos dados de alerta de amostra.

Autenticar solicitações de Webhook

O campo Webhook Secret armazena um segredo que o Cloud Manager usa somente para gerar o cabeçalho X-MMS-Signature para verificação da solicitação. O Cloud Manager não envia o segredo diretamente como um cabeçalho de autenticação ou token de portador.

Se o ponto de extremidade do webhook exigir autenticação, você deverá lidar com ela de forma independente usando um dos seguintes métodos:

• Parâmetros de query: Inclua credenciais de autenticação no Webhook URL como parâmetros de query. Por exemplo: https://example.com/webhook?token=your-auth-token

• Lista de acesso IP: configure seu endpoint do webhook para aceitar solicitações somente de endereços IP do Cloud Manager . Essa configuração garante que somente o Cloud Manager possa enviar solicitações para seu endpoint.

• Proxy reverso ou gateway de API: use um proxy reverso ou gateway de API que lide com a autenticação antes de encaminhar solicitações para o endpoint do webhook.

Limitações

Ao usar integrações de webhook, considere as seguintes limitações:

Configuração de firewall

Se o firewall exigir que você configure uma lista de acesso IP, permita o acesso a partir de endereços IP do Cloud Manager para que o Cloud Manager possa se comunicar com o endpoint do webhook.

Solucionar problemas de entrega de webhook

Se o seu webhook não receber alertas: