Você pode configurar o Atlas para enviar notificações de alerta para um ponto de extremidade de webhook como solicitações de publicação HTTP para processamento programático. Os webhooks permitem que você integre alertas do Atlas com sistemas de monitoramento personalizados, plataformas de gerenciamento de incidentes ou fluxos de trabalho de automação.
Acesso necessário
Para integrar o Atlas com webhooks, você deve ter acesso do Organization Owner ou do Project Owner ao projeto.
Configurar uma integração de Webhook
No Atlas, vá para a página Project Settings.
Se ainda não tiver sido exibido, selecione a organização que contém seu projeto 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.
Na barra lateral, clique no ícone ao lado de Project Overview.
A página Configurações do projeto é exibida.
No Atlas, vá para a página Project Integrations.
Clique na aba Integrations.
A página Integrações de projeto é exibida.
(Opcional) Personalize os modelos de webhook.
Você pode personalizar os cabeçalhos de solicitação e o conteúdo do corpo usando modelos FreeMarker:
No campo Webhook Headers Template, insira um modelo FreeMarker para personalizar os cabeçalhos HTTP enviados com solicitações de webhook.
No campo Webhook Body Template, insira um modelo FreeMarker para personalizar a estrutura do corpo da solicitação.
Se você configurar modelos e, posteriormente, visualizar ou editar a integração do webhook, os modelos aparecerão redigidos com ******. Você pode substituir os modelos redigidos por novos valores.
O Atlas valida a sintaxe do FreeMarker ao salvar a configuração. Se o seu modelo contiver sintaxe inválida, o formulário exibirá um erro de validação em linha.
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 Atlas inclui os seguintes cabeçalhos HTTP em cada solicitação de webhook:
Cabeçalho | Descrição |
|---|---|
| Indica o estado do alerta. Valores possíveis:
|
| (Opcional) Se você especificar um segredo no campo Webhook Secret, o Atlas incluirá este cabeçalho. Contém a assinatura HMAC-SHA-1 codificada em Base64do corpo da solicitação. O Atlas cria a assinatura usando o segredo fornecido. Use este cabeçalho para verificar se a solicitação de webhook se originou do Atlas. |
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 Atlas Administration API. 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).humanReadableDescrição legível por humanos do alerta. Este campo contém o nome do projeto e o nome da organização no formato "Projeto: [nome do projeto] Organização: [nome da organização]" junto com outros detalhes do alerta.
Para obter uma lista completa de campos, consulte a documentação da Atlas Administration API Obter todos os alertas de projeto.
Exemplo de carga útil de webhook
O exemplo a seguir mostra um payload de webhook de amostra para um alerta de espaço em 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 solicitações de Webhook
O campo Webhook Secret armazena um segredo que o Atlas usa exclusivamente para gerar o cabeçalho X-MMS-Signature para verificação de solicitações. O Atlas não envia o segredo diretamente como um cabeçalho de autenticação ou Bearer token.
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-tokenLista de acesso IP: configure seu ponto de extremidade de webhook para aceitar solicitações somente de endereços IP do Atlas. Essa configuração garante que somente o Atlas possa enviar solicitações para seu ponto de extremidade.
Proxy reverso ou API Gateway: use um proxy reverso ou API Gateway que lide com a autenticação antes de encaminhar as solicitações para o ponto de extremidade do webhook.
Verificar solicitações de webhook
Para verificar se uma solicitação de webhook se originou do Atlas, valide o cabeçalho X-MMS-Signature:
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 Atlas. Para recuperar a gravidade configurada, faça uma chamada adicional para o ponto de extremidade Obter uma configuração de alerta da Atlas Administration API usando o alertConfigId do payload do webhook.
Nenhum alerta de teste manual
O Atlas 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 fáceis de trigger, como:
Um limite de pouco espaço em disco em um cluster 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
Se o seu firewall exigir que você configure uma lista de acesso IP, permita o acesso a partir de endereços IP do Atlas para que o Atlas possa se comunicar com o ponto de extremidade do webhook.
Solucionar problemas de entrega de webhook
Se o seu webhook não receber alertas: