Você pode configurar o MongoDB Ops Manager para enviar notificações de alerta para um ponto de extremidade de webhook como solicitações POST HTTP em processamento programático. Webhooks permitem integrar alertas do MongoDB Ops Manager com sistemas de monitoramento personalizados, plataformas de gerenciamento de incidentes ou fluxos de trabalho de automação.
Acesso necessário
Para integrar o MongoDB Ops Manager com webhooks, você deve ter acesso do Project Monitoring Admin ao projeto.
Autenticar solicitações de Webhook
Você pode autenticar solicitações de webhook com os seguintes métodos:
Segredo do webhook: o MongoDB Ops Manager usa o segredo para gerar o cabeçalho
X-MMS-Signature. O MongoDB Ops Manager não envia o segredo em si como um cabeçalho de autenticação ou Bearer token. Para aprender como verificar a assinatura, consulte Verificar solicitações de webhook.Credenciais de cliente OAuth 2.0 : o MongoDB Ops Manager obtém um token de acesso de portador do seu ponto de extremidade de token OAuth 2.0 e o envia no cabeçalho
Authorization. Para configurar este método, consulte Configurar uma integração de webhook.
Você pode usar um método, ambos ou nenhum. Se você configurar ambos, o MongoDB Ops Manager incluirá os cabeçalhos Authorization e X-MMS-Signature na mesma solicitação.
O MongoDB Ops Manager faz cache do token de acesso OAuth 2.0 e o atualiza quando o token expira. Se o seu ponto de extremidade de webhook retornar uma resposta 401, o MongoDB Ops Manager atualizará o token e tentará novamente a solicitação uma vez.
Comportamento do modelo de cabeçalhos personalizados
Se você configurar um modelo de cabeçalhos personalizados, ele substituirá os cabeçalhos padrão na solicitação. O MongoDB Ops Manager não adiciona os cabeçalhos X-MMS-Signature ou Authorization para você. Para incluir qualquer um dos cabeçalhos, adicione-o ao seu modelo:
"X-MMS-Signature": "${signature}""Authorization": "Bearer ${oauthToken}"
Para aprender mais sobre modelos de webhook, consulte Configurar modelo de webhook.
Outros métodos de autenticação
Se o segredo do webhook e as credenciais de cliente OAuth 2.0 não atenderem às suas necessidades, você pode lidar com a autenticação de uma das seguintes maneiras:
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-tokenLista de acesso IP: configure seu ponto de extremidade de webhook para aceitar solicitações apenas dos endereços IP da sua instância do MongoDB Ops Manager.
Proxy reverso ou API Gateway: Use um proxy reverso ou um API Gateway que lida com a autenticação antes de encaminhar as solicitações para o seu ponto de extremidade de webhook.
Verificar solicitações de webhook
Para verificar se uma solicitação de webhook se originou do MongoDB Ops Manager, valide o cabeçalho X-MMS-Signature:
Configurar uma integração de Webhook
Navegue até a Project Integrations página.
Se ainda não estiver exibido, selecione a organização que contém o projeto desejado no menu Organizations na barra de navegação.
Se ainda não estiver exibido, selecione o projeto desejado no menu Projects na barra de navegação.
Clique em Integrations no painel de navegação esquerdo sob o título Settings.
Configurar autenticação.
Insira pelo menos uma das seguintes opções de autenticação:
Webhook Secret: Insira uma chave secreta. O MongoDB Ops Manager usa esse segredo para gerar o cabeçalho
X-MMS-Signaturepara verificação de solicitação.OAuth2 Token URL, OAuth2 Client ID e OAuth2 Client Secret: insira o ponto de extremidade do token que o MongoDB Ops Manager chama para obter um token de acesso e as credenciais do aplicativo que você registrou com seu provedor OAuth 2.0. Defina todos os três valores juntos ou deixe todos os três vazios.
Você pode usar ambas as opções juntas. Para saber mais, consulte Autenticar solicitações de webhook.
Para enviar alertas ao seu webhook, configure as notificações de alerta. Para saber mais, consulte Configurar definições de alerta no MongoDB Ops Manager.
Cabeçalhos de solicitação
O Ops Manager inclui os seguintes cabeçalhos HTTP em cada solicitação de webhook:
O Ops 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:
| O alerta acabou de ser aberto. |
| O alerta foi resolvido. |
| Um alerta aberto anteriormente ainda está aberto. |
| O alerta foi reconhecido. |
| O alerta tornou-se inválido e foi cancelado. |
| Representa um alerta informativo, que é um evento pontual, como "Primário eleito". |
Se você especificar uma chave no campo Webhook Secret, o MongoDB Ops Manager adicionará o cabeçalho de solicitação X-MMS-Signature. Este cabeçalho contém a assinatura HMAC-SHA-1 codificada em Base64do corpo da solicitação. O MongoDB Ops Manager cria a assinatura usando o segredo fornecido.
Se você configurar as credenciais de cliente OAuth 2.0, o MongoDB Ops Manager adicionará o cabeçalho de solicitação Authorization. Este cabeçalho contém o token de acesso do portador que o MongoDB Ops Manager obtém do seu ponto de extremidade de token OAuth 2.0.
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 MongoDB Ops Manager. O payload inclui campos-chave 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 campo, consulte a documentação do ponto de extremidade Get One Alerta.
Exemplo de carga útil de webhook
O exemplo a seguir mostra uma amostra de payload de webhook para um alerta de limite 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" }}Personalize modelos de webhook
Você pode personalizar os cabeçalhos da solicitação e o conteúdo do corpo usando modelos FreeMarker. Para obter informações detalhadas sobre a modelagem de webhook, incluindo variáveis de modelo disponíveis, assistentes de regex e exemplos, veja Configurar modelagem de webhook.
Limitações
Ao usar integrações de webhook, considere as seguintes limitações:
Gravidade do alerta não incluída
O payload do webhook não inclui o nível de gravidade do alerta que você configura no MongoDB Ops Manager. Para recuperar a gravidade configurada, faça uma chamada adicional ao ponto de extremidade Obter uma configuração de alerta usando o alertConfigId do payload do webhook.
Nenhum alerta de teste manual
O MongoDB Ops Manager não oferece uma maneira de trigger alertas de teste manualmente. Para testar seu ponto de extremidade de webhook, você pode configurar temporariamente um alerta com condições que você pode trigger, como:
Um limite de espaço em disco baixo em uma implantação de teste.
Um limite de contagem de conexões que você pode trigger abrindo várias conexões.
Um limite de atraso de replicação em um conjunto de réplicas de teste.
Depois de confirmar que seu webhook está recebendo alertas corretamente, você pode excluir a configuração de alerta de teste.
Configuração de firewall
Como o MongoDB Ops Manager é auto-hospedado, certifique-se de que sua rede permita solicitações HTTP de saída do servidor do MongoDB Ops Manager para o ponto de extremidade do seu webhook. Se o seu ponto de extremidade de webhook estiver atrás de um firewall, adicione o endereço IP do servidor do Ops Manager à lista de acesso IP do ponto de extremidade.
Solucionar problemas de entrega de webhook
Se o seu webhook não receber alertas: