Table of Contents
4 Webhook
Vis?o geral
O tipo de m¨ªdia webhook ¨¦ ¨²til para chamadas HTTP customizadas de c¨®digo JavaScript para integra??o direta com software externos como sistemas de helpdesk, chats, ou mensageiros. Voc¨º pode escolher importar uma integra??o provida pelo Áú»¢¶Ä²© ou criar uma integra??o customizada do zero.
Integra??es
As seguintes integra??es est?o dispon¨ªveis, permitindo que tipos de m¨ªdia de webhook predefinidos sejam usados para enviar notifica??es do Áú»¢¶Ä²© para:
Al¨¦m dos servi?os listados aqui, o Áú»¢¶Ä²© pode ser integrado com Spiceworks (nenhum webhook ¨¦ necess¨¢rio). Para converter notifica??es do Áú»¢¶Ä²© em tickets do Spiceworks, crie um email media type e insira o endere?o de email do helpdesk do Spiceworks (por exemplo, [email protected]) nas configura??es de perfil de um usu¨¢rio designado do Áú»¢¶Ä²©.
Configura??o
Para come?ar a usar uma integra??o de webhook:
- Localize o arquivo .xml necess¨¢rio no diret¨®rio
templates/mediada vers?o baixada do Áú»¢¶Ä²© ou baixe-o do - Importe Import o arquivo na sua instala??o do Áú»¢¶Ä²©. 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 Administra??o ¡ú Tipos de m¨ªdia
- Clique em Criar um 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 s?o marcados com um asterisco vermelho.
| Par?metro | Descri??o |
|---|---|
| Par?metros | Especifique as vari¨¢veis do webhook como pares de atributos e valores. Para webhooks preconfigurados, uma 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, m¨²ltiplas vari¨¢veis comuns s?o inclu¨ªdas por padr?o (URL:<empty>, HTTPProxy:<empty>, To:{ALERT.SENDTO}, Subject:{ALERT.SUBJECT}, Message:{ALERT.MESSAGE}), sinta-se ¨¤ vontade para mant¨º-las ou remov¨º-las. Todos os macros macros que s?o suportados em notifica??es de problemas s?o suportados nos par?metros. Se voc¨º especificar um proxy HTTP, o campo suporta a mesma funcionalidade que no campo de configura??o do item do HTTP proxy. 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 bloco que aparece ao clicar no campo do par?metro (ou no bot?o de visualiza??o/edi??o 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 solicita??es HTTP GET, POST, PUT e DELETE e tem controle sobre 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. 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 a cria??o de um alerta. Se o script estiver configurado para retornar e processar tags, essas tags n?o ser?o resolvidas nos macros {EVENT.TAGS} e {EVENT.RECOVERY.TAGS} na mensagem inicial do problema e nas mensagens de recupera??o, pois o script ainda n?o teve tempo de ser executado. Nota: Usar vari¨¢veis locais em vez de globais ¨¦ recomendado para garantir que cada script opere em seus pr¨®prios dados e que n?o haja colis?es entre chamadas simult?neas (veja known issues). Veja tamb¨¦m: Webhook development guidelines, Webhook script examples, Additional JavaScript objects. |
| 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 valores de propriedades JSON retornadas como tags. Essas tags s?o adicionadas ¨¤s tags de eventos de problema j¨¢ existentes (se houver) no Áú»¢¶Ä²©. Se um webhook usar tags (a caixa de sele??o Processar tags estiver marcada), o webhook deve sempre retornar um objeto JSON contendo pelo menos um objeto vazio para tags: var result = {tags: {}};.Exemplos de tags que podem ser retornadas: Jira ID: PROD-1234, Responsible: John Smith, Processed:<no value>, etc. |
| Incluir entrada no menu de eventos | Marque a caixa de sele??o para incluir uma entrada no event menu vinculando ao ticket externo criado. Se marcado, o webhook n?o deve ser usado para enviar notifica??es para diferentes usu¨¢rios (considere criar um dedicated user em vez disso) ou em v¨¢rias a??es de alerta related to a single problem event. |
| Nome da entrada no menu | Especifique o nome da entrada no menu. {EVENT.TAGS.<tag name>} macro ¨¦ suportado. Este campo ¨¦ obrigat¨®rio apenas se Incluir entrada no menu de eventos estiver selecionado. |
| URL da entrada no menu | Especifique o URL subjacente da entrada no menu. {EVENT.TAGS.<tag name>} macro ¨¦ suportado. Este campo ¨¦ obrigat¨®rio apenas se Incluir entrada no menu de eventos estiver selecionado. |
Para mais detalhes sobre como configurar mensagens padr?o e op??es de processamento de alertas, consulte common media type parameters.
Mesmo que um webhook n?o use mensagens padr?o, os templates de mensagens para tipos de opera??o usados por este webhook ainda devem ser definidos.
²Ñ¨ª»å¾±²¹ do usu¨¢rio
Depois que o tipo de m¨ªdia estiver configurado, v¨¢ para a se??o Administra??o ¡ú ±«²õ³Ü¨¢°ù¾±´Çs e atribua a m¨ªdia do webhook a um usu¨¢rio existente ou crie um novo usu¨¢rio para representar o webhook. Os passos para configurar a m¨ªdia do usu¨¢rio para um usu¨¢rio existente, sendo comum para todos os tipos de m¨ªdia, est?o descritos na p¨¢gina Media types .
Se um webhook usar tags para armazenar o ID do ticket/mensagem, evite atribuir o mesmo webhook como m¨ªdia a diferentes usu¨¢rios, 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 melhor pr¨¢tica ¨¦ criar um usu¨¢rio dedicado para representar o webhook:
- Ap¨®s configurar o tipo de m¨ªdia do webhook, v¨¢ para a se??o Administra??o ¡ú ±«²õ³Ü¨¢°ù¾±´Çs e crie um usu¨¢rio Áú»¢¶Ä²© 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 nos padr?es, pois esse usu¨¢rio n?o far¨¢ login no Áú»¢¶Ä²©.
- No perfil do usu¨¢rio, v¨¢ para a aba ²Ñ¨ª»å¾±²¹ 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 permissions a todos os hosts para os quais ele deve enviar os alertas.
Ao configurar a a??o de alerta, adicione este usu¨¢rio no campo Enviar para usu¨¢rios nos detalhes da opera??o - isso informar¨¢ ao Áú»¢¶Ä²© para usar o webhook para notifica??es desta 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 configuring actions envolvendo webhooks s?o os mesmos que para todos os outros tipos de m¨ªdia, com as seguintes exce??es:
- Se um webhook usar tags para armazenar ID de ticket/mensagem e para acompanhar opera??es de atualiza??o/resolu??o, esse webhook n?o deve ser usado em v¨¢rias a??es de alerta para um ¨²nico evento de problema. Se
{EVENT.TAGS.<name>} j¨¢ existir e for atualizado no webhook, o valor resultante n?o ser¨¢ definido. Para esse caso, deve-se usar um novo nome de tag no webhook para armazenar valores atualizados. Isso se aplica aos webhooks do Jira, Jira Service Desk, Mattermost, Opsgenie, OTRS, Redmine, ServiceNow, Slack, Zammad e Zendesk fornecidos pelo Áú»¢¶Ä²© e ¨¤ maioria dos webhooks que utilizam a op??o Incluir entrada de menu de evento. Usar o webhook em v¨¢rias opera??es ¨¦ permitido se essas opera??es ou etapas de escalonamento pertencerem ¨¤ mesma a??o. Tamb¨¦m ¨¦ permitido usar esse webhook em diferentes a??es se as a??es n?o forem aplicadas ao mesmo evento de problema devido a diferentes condi??es de filtro. - Ao usar um webhook em a??es para eventos internos internal events: na configura??o da opera??o de a??o, marque a caixa Mensagem personalizada e defina a mensagem personalizada, caso contr¨¢rio, uma notifica??o n?o ser¨¢ enviada.