4 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 o uso de 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 chamados do Spiceworks, crie um tipo de mídia de e-mail e insira o endereço de e-mail do helpdesk do Spiceworks (por exemplo, [email protected]) nas configurações de perfil de um usuário Zabbix designado.

Configuração

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

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

Para criar um webhook personalizado do zero:

Vá para Alertas > Tipos de mídia.
Clique em Criar tipo de mídia.

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

Todos os campos obrigatórios estão marcados com um asterisco vermelho.

Os seguintes parâmetros 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 dependendo do serviço. Verifique o arquivo Readme.md do webhook para a descrição dos parâmetros. Para novos webhooks, várias variáveis comuns são incluídas por padrão (URL:<vazio>, HTTPProxy:<vazio>, To:{ALERT.SENDTO}, Subject:{ALERT.SUBJECT}, Message:{ALERT.MESSAGE}), fique à vontade para mantê-las ou removê-las. Os parâmetros do webhook suportam macros de usuário, todas as macros que são suportadas em notificações de problemas e, adicionalmente, as macros {ALERT.SENDTO}, {ALERT.SUBJECT} e {ALERT.MESSAGE}. Se você especificar um proxy HTTP, o campo suporta a mesma funcionalidade que o campo proxy HTTP na configuração do item. A string do proxy pode ser prefixada com `[scheme]://` para especificar qual tipo de proxy é usado (por exemplo, https, socks4, socks5; veja a documentação).
Script	Insira o código JavaScript no editor modal que abre ao clicar no campo de parâmetro ou no ícone de lápis ao lado dele. Este código executará a operação do webhook. O script é um código de função que aceita pares de parâmetro - 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 requisições HTTP GET, POST, PUT e DELETE e tem controle sobre os cabeçalhos HTTP e o corpo da requisição. O script deve conter um operador return, caso contrário, não será válido. Ele pode retornar o status OK junto com uma lista opcional de tags e valores de tags (veja a opção Processar tags) ou uma string de erro. Observe que o script é executado apenas após um alerta ser criado. Se o script estiver configurado para retornar e processar tags, essas tags não serão resolvidas nas macros {EVENT.TAGS} e {EVENT.RECOVERY.TAGS} na mensagem inicial de problema e nas mensagens de recuperação porque o script ainda não teve tempo de ser executado. Nota: Usar variáveis locais (por exemplo, `var local = 1`) em vez de globais (por exemplo, `global = 1`) é recomendado para garantir que cada script opere em seus próprios dados e evitar colisões entre chamadas simultâneas (veja problemas conhecidos). Veja também: Diretrizes de desenvolvimento de webhook, Exemplos de scripts de webhook, Objetos JavaScript adicionais.
Timeout	Tempo limite de execução do JavaScript (1-60s, padrão 30s). Sufixos de tempo são suportados, 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 tags vazio: `var result = {tags: {}};` Exemplos de tags que podem ser retornadas: jira-id:prod-1234, responsible:John Smith, processed:<sem valor>
Incluir entrada no menu de eventos	Marque a caixa de seleção para incluir uma entrada no menu de eventos vinculando a um ticket externo criado. Uma entrada será incluída para cada webhook que estiver habilitado e tiver esta caixa marcada. Observe que se os parâmetros Nome da entrada do menu e URL da entrada do menu contiverem quaisquer macros {EVENT.TAGS.<tag name>}, uma entrada será incluída apenas se essas macros puderem ser resolvidas (ou seja, o evento tiver essas tags definidas). Se marcada, o webhook não deve ser usado para enviar notificações para diferentes usuários (considere criar um usuário dedicado em vez disso) 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>} é suportada. 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>} é suportada. Este campo só é obrigatório se Incluir entrada no menu de eventos estiver marcado.

Veja parâmetros comuns de tipo de mídia para 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 modelos de mensagem para os tipos de operação usados por este webhook ainda devem ser definidos.

Testando

Para testar um tipo de mídia webhook configurado:

Localize o webhook relevante na lista de tipos de mídia.
Clique em Testar na última coluna da lista (uma janela de teste será aberta).
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á.
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 de log do 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 que o tipo de mídia for configurado, vá para 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 para um usuário existente, sendo comuns para 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 para diferentes usuários, pois isso pode causar erros no webhook (aplica-se à maioria dos webhooks que utilizam a opção Incluir entrada de menu de evento). Nesse caso, a melhor prática é criar um usuário dedicado para representar o webhook:

Após configurar o tipo de mídia webhook, vá para 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 ser deixadas como padrão, pois esse usuário não fará login no Zabbix.
No perfil do usuário, vá até a guia 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 suportados para contornar os requisitos de validação.
Conceda a esse usuário pelo menos permissões de leitura permissões para todos os hosts para os quais ele deve enviar os alertas.

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

Configurando ações de alerta

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

Se um webhook usa tags de webhook para armazenar o ID do ticket\mensagem e lidar com 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 atualizada 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 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 Incluir entrada de menu de evento. 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 diferentes ações 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 Mensagem personalizada e definir uma mensagem personalizada na configuração da operação da ação. Caso contrário, uma notificação não será enviada.

Documentation