webhook

Visão geral

O tipo de mídia webhook é útil para fazer chamadas HTTP usando código JavaScript personalizado para integração direta com softwares externos, como sistemas de helpdesk, chats ou mensageiros. Você pode optar por importar uma integração fornecida pelo Zabbix ou criar uma integração personalizada do zero.

Integrações

As seguintes integrações estão disponíveis, permitindo usar tipos de mídia webhook predefinidos para enviar notificações do Zabbix para:

Além dos serviços listados aqui, o Zabbix pode ser integrado ao Spiceworks (nenhum webhook é necessário). Para converter notificações do Zabbix em tickets do Spiceworks, crie um tipo de mídia de e-mail e informe o endereço de e-mail do helpdesk do Spiceworks (por exemplo, [email protected]) nas configurações de perfil de um usuário do Zabbix designado.

Configuração

Para começar a usar uma integração de webhook:

  1. Localize o arquivo .yaml necessário no diretório templates/media da versão baixada do Zabbix ou baixe-o do repositório git do Zabbix.
  2. Importe o arquivo para a sua instalação do Zabbix. O webhook aparecerá na lista de tipos de mídia.
  3. Configure o webhook de acordo com as instruções no arquivo Readme.md (você pode clicar no nome de um webhook acima para acessar rapidamente o arquivo Readme.md).

Para criar um webhook personalizado do zero:

  1. Acesse Alertas > Tipos de mídia.
  2. Clique em Criar tipo de mídia.
  3. Insira os parâmetros do tipo de mídia webhook no formulário.

A aba Tipo de mídia contém vários atributos específicos para este tipo de mídia:

Todos os campos de entrada obrigatórios são marcados com um asterisco vermelho.

Os parâmetros a seguir são específicos para o tipo de mídia webhook:

Parâmetro Descrição
Parâmetros Especifique as variáveis do webhook como pares de atributo e valor.
Para webhooks pré-configurados, a lista de parâmetros varia de acordo com o serviço. Consulte o arquivo Readme.md do webhook para obter a descrição dos parâmetros.
Para novos webhooks, várias variáveis comuns são incluídas por padrão (URL:<empty>, HTTPProxy:<empty>, To:{ALERT.SENDTO}, Subject:{ALERT.SUBJECT}, Message:{ALERT.MESSAGE}); você pode mantê-las ou removê-las.

Os parâmetros do webhook são compatíveis com macros de usuário, todas as macros compatíveis com notificações de problemas e, adicionalmente, com as macros {ALERT.SENDTO}, {ALERT.SUBJECT} e {ALERT.MESSAGE}.

Se você especificar um proxy HTTP, o campo será compatível com a mesma funcionalidade do campo proxy HTTP na configuração do item. A string do proxy pode ser prefixada com [scheme]:// para especificar o tipo de proxy usado (por exemplo, https, socks4, socks5; consulte a documentação).
Script Insira o código JavaScript no editor modal que é aberto ao clicar no campo do parâmetro ou no ícone de lápis ao lado dele. Esse código executará a operação do webhook.
O script é um código de função que aceita pares de parâmetro e valor. Os valores devem ser convertidos em objetos JSON usando o método JSON.parse(), por exemplo: var params = JSON.parse(value);.

O código tem acesso a todos os parâmetros, pode executar solicitações HTTP GET, POST, PUT e DELETE, oferecer suporte a métodos adicionais, como CONNECT, PATCH, HEAD, OPTIONS e TRACE, e controlar os cabeçalhos HTTP e o corpo da solicitação.
O script deve conter um operador return; caso contrário, não será válido. Ele pode retornar um status OK junto com uma lista opcional de tags e valores de tags (consulte a opção Processar tags) ou uma string de erro.

Os eventos de recuperação (gerados automaticamente ou como resultado de um fechamento manual) são criados pelo server e incluem tags de evento resolvidas (incluindo tags herdadas de templates, hosts e triggers). Os scripts de webhook são executados depois que o alerta é criado; portanto, as tags retornadas por um script de webhook são adicionadas somente após a criação inicial do alerta e não estarão presentes nas macros {EVENT.TAGS} e {EVENT.RECOVERY.TAGS} da mensagem inicial do problema ou da mensagem de recuperação imediata.
Observação: recomenda-se usar variáveis locais (por exemplo, var local = 1) em vez de variáveis globais (por exemplo, global = 1) para garantir que cada script opere sobre seus próprios dados e evitar colisões entre chamadas simultâneas (consulte os problemas conhecidos).

Consulte também: Diretrizes de desenvolvimento de webhook, Exemplos de scripts de webhook, Objetos JavaScript adicionais.
Tempo limite Tempo limite de execução do JavaScript (1-60s, padrão: 30s).
Sufixos de tempo são compatíveis (por exemplo, 30s, 1m).
Processar tags Marque a caixa de seleção para processar os valores das propriedades JSON retornadas como tags. Essas tags são adicionadas a quaisquer tags de problema existentes.
Observe que, ao usar tags de webhook, o webhook deve retornar um objeto JSON contendo pelo menos um objeto de tags vazio: var result = {tags: {}};
Exemplos de tags que podem ser retornadas: jira-id:prod-1234, responsible:John Smith, processed:<no value>
Incluir entrada no menu de eventos Marque a caixa de seleção para incluir uma entrada no menu de eventos com um link para um ticket externo criado.
Uma entrada será incluída para cada webhook habilitado que tenha esta caixa de seleção marcada. Observe que, se os parâmetros Nome da entrada do menu e URL da entrada do menu contiverem macros {EVENT.TAGS.<tag name>}, uma entrada será incluída somente se essas macros puderem ser resolvidas (ou seja, se o evento tiver essas tags definidas).
Se marcada, o webhook não deve ser usado para enviar notificações a usuários diferentes (considere criar um usuário dedicado) e não deve ser usado em várias ações de alerta para um único evento de problema.
Nome da entrada do menu Especifique o nome da entrada do menu.
A macro {EVENT.TAGS.<tag name>} é compatível.
Este campo só é obrigatório se Incluir entrada no menu de eventos estiver marcado.
URL da entrada do menu Especifique a URL subjacente da entrada do menu.
A macro {EVENT.TAGS.<tag name>} é compatível.
Este campo só é obrigatório se Incluir entrada no menu de eventos estiver marcado.

Consulte parâmetros comuns de tipo de mídia para obter detalhes sobre como configurar mensagens padrão e opções de processamento de alertas.

Mesmo que um webhook não use mensagens padrão, os templates de mensagem para os tipos de operação usados por esse webhook ainda deverão ser definidos.

Teste

Para testar um tipo de mídia webhook configurado:

  1. Localize o webhook relevante na lista de tipos de mídia.
  2. Clique em Testar na última coluna da lista (uma janela de teste será aberta).
  3. Edite os valores dos parâmetros do webhook conforme necessário.
    Substitua as macros por valores de exemplo; caso contrário, as macros não serão resolvidas e o teste falhará.
  4. Clique em Testar.

Substituir ou excluir valores na janela de teste afeta apenas o procedimento de teste; os valores reais dos atributos do webhook permanecerão inalterados.

Para visualizar as entradas do log de teste do tipo de mídia sem sair da janela de teste, clique em Abrir log (uma nova janela pop-up será aberta).

Se o teste do webhook for bem-sucedido:

  • A mensagem "Teste do tipo de mídia bem-sucedido." é exibida.
  • A resposta do servidor aparece no campo cinza Resposta.
  • O tipo de resposta (JSON ou String) é especificado abaixo do campo Resposta.

Se o teste do webhook falhar:

  • A mensagem "Media type test failed." é exibida, seguida de detalhes adicionais sobre a falha.

Mídia do usuário

Depois de configurar o tipo de mídia, acesse a seção Usuários > Usuários e atribua a mídia webhook a um usuário existente ou crie um novo usuário para representar o webhook. As etapas para configurar a mídia do usuário existente, que são comuns a todos os tipos de mídia, estão descritas na página Tipos de mídia.

Se um webhook usar tags para armazenar o ID do ticket\mensagem, evite atribuir o mesmo webhook como mídia a usuários diferentes, pois isso pode causar erros no webhook (aplica-se à maioria dos webhooks que utilizam a opção Incluir entrada no menu de eventos). Nesse caso, a prática recomendada é criar um usuário dedicado para representar o webhook:

  1. Depois de configurar o tipo de mídia webhook, acesse a seção Usuários > Usuários e crie um usuário Zabbix dedicado para representar o webhook - por exemplo, com o nome de usuário Slack para o webhook do Slack. Todas as configurações, exceto a mídia, podem permanecer com os valores padrão, pois esse usuário não fará login no Zabbix.
  2. No perfil do usuário, acesse a aba Mídia e adicione um webhook com as informações de contato necessárias. Se o webhook não usar um campo Enviar para, insira qualquer combinação de caracteres compatíveis para atender aos requisitos de validação.
  3. Conceda a esse usuário pelo menos permissões de leitura para todos os hosts para os quais ele deverá enviar os alertas.

Ao configurar a ação de alerta, adicione esse usuário ao campo Enviar para usuários em Detalhes da operação - isso informará ao Zabbix que deve usar o webhook para as notificações dessa ação.

Configurando ações de alerta

As ações determinam quais notificações devem ser enviadas via webhook. As etapas para configurar ações envolvendo webhooks são as mesmas que para todos os outros tipos de mídia, com estas exceções:

  • Se um webhook usar webhook tags para armazenar o ID da ticket\mensagem e tratar operações de atualização\resolução, evite usar o mesmo webhook em várias ações de alerta para um único evento de problema. Se {EVENT.TAGS.<tag name>} existir e for atualizado no webhook, seu valor resultante será indefinido. Para evitar isso, use um novo nome de tag no webhook para armazenar valores atualizados. Isso se aplica aos webhooks de Jira, Jira Service Desk, Mattermost, Opsgenie, OTRS, Redmine, ServiceNow, Slack, Zammad e Zendesk fornecidos pelo Zabbix e à maioria dos webhooks que utilizam a opção Include event menu entry. Observe, no entanto, que um único webhook pode ser usado em várias operações ou etapas de escalonamento da mesma ação, bem como em ações diferentes que não serão acionadas pelo mesmo evento de problema devido a diferentes condições.
  • Ao usar um webhook em ações para eventos internos, certifique-se de marcar a caixa de seleção Custom message e definir uma mensagem personalizada na configuração da operação da ação. Caso contrário, uma notificação não será enviada.