Webhooks

Webhooks é uma funcionalidade que permite integrar o Portal com ferramentas de terceiros para o envio de notificações quando ocorrem determinados eventos na organização.

Eventos disponíveis:

• Alerta ativada
• Microserviço executado
• Objeto criado
• Objeto modificado
• Objeto eliminado
• Operação executada
• Operação executada em um workspace

Quando ocorre um desses eventos, o Portal faz uma chamada HTTP para a URL configurada pela organização e envia uma mensagem com a informação correspondente. O aplicativo de destino pode usar esses dados para executar ações como criar um ticket em um sistema ITSM, enviar uma mensagem por Slack ou Microsoft Teams, mandar um email, entre outros.

Esta ferramenta só pode ser configurada por um usuário com o papel de Administrador de organização.

Visão geral

A tela principal mostra a lista de webhooks configurados na organização, indicando se estão habilitados ou desabilitados. A tabela inclui:

• Nome. Nome atribuído ao webhook. Ao clicar, você acessa sua visão de detalhe.
• Tipo de evento. Evento que ativará o webhook.
• URL de destino. Endereço do sistema externo que recebe o evento e age conforme a informação provida na mensagem.
• Estado. Indica se o webhook está Habilitado ou Desabilitado.

Criar uma integração webhook

Para criar um novo webhook devem ser seguidos os seguintes passos:

1. No Portal, acessar Configuração -> Integrações Webhook.

2. Clicar em Novo.

3. Preencher e configurar cada seção do formulário:

   Visão geral

   

   • Nome. Nome atribuído ao webhook.
   • Tipo de evento. Evento que ativará o webhook.
   • URL de destino. Endereço do sistema externo que recebe o evento e age conforme a informação provida na mensagem.

   Elementos

   

   O conteúdo desta tabela depende do tipo de evento selecionado.

   • Alerta ativada

     • Mostra a lista de alertas ativos da organização para selecionar quais irão enviar o webhook.

     • Enviar webhook para todas as alertas - Ativa o webhook para todas as alertas.

   • Microserviço executado

     • Mostra a lista de microserviços habilitados para selecionar quais irão enviar o webhook.

     • Enviar webhook para todos os microserviços - Ativa o webhook para todos os microserviços.

     • Em ambos os casos, o botão Ver permite acessar a visão de detalhe do recurso.

   • Objeto criado, Objeto modificado ou Objeto eliminado

     • Mostra uma lista para selecionar o objeto que enviará o webhook após a ação correspondente.

     • Enviar webhook para todos os objetos - Ativa o webhook para todos os objetos.

   • Operação executada

     • Mostra uma lista para selecionar a operação que enviará o webhook quando executada.

     • Enviar webhook para todas as operações - Ativa o webhook para todas as operações.

   • Operação executada em um workspace

     • Mostra uma lista para selecionar a operação que enviará um webhook para cada dispositivo onde foi executada.

     • Enviar webhooks para todas as operações executadas em cada workspace - Ativa o webhook para todas as operações por dispositivo.

     nota

     • As operações podem ser executadas em um ou mais dispositivos.

     • O evento Operação executada permite enviar um webhook a nível global.

     • O evento Operação executada em um workspace permite enviar um webhook para cada um dos dispositivos em que a operação foi executada.

       Exemplo:

       Se a operação Reiniciar for executada em três dispositivos simultaneamente, serão gerados:

       • Uma notificação webhook de tipo Operação executada.
       • Três notificações webhook de tipo Operação executada em um workspace.

   Configuração da mensagem

   

   Nesta seção, define-se a mensagem que será enviada quando ocorrer o evento. A configuração utiliza o formato JSON e determina a estrutura e o conteúdo da mensagem transmitida ao sistema externo.

   As variáveis são substituídas automaticamente por valores reais quando ocorre o evento.

4. Clicar em Salvar.

aviso

Uma organização não deve ter dois webhooks com a mesma configuração porque pode gerar envios duplicados.

Variáveis disponíveis para a mensagem

Todos os tipos de eventos

Variáveis	Descrição
#event_type	Tipo de evento
#organization_id	ID da organização
#organization_name	Nome da organização/inquilino
#timestamp	Data e hora do evento (ISO 8601)

Alerta ativada

Variáveis	Descrição
#alert_name	Nome da alerta
#alert_information	Informação adicional da alerta
#alert_start	Data e hora de início da alerta (ISO 8601)
#alert_element	Elemento que desencadeou a alerta
#workspace_id	ID do dispositivo
#workspace_name	Nome do dispositivo
#workspace_last_user	Último usuário que usou o dispositivo
#workspace_reporting_group_id	ID do grupo de relatório
#workspace_reporting_group_name	Nome do grupo de relatório

Exemplo de template

{
    "message": {
        "event_type": "#event_type",
        "organization_id": "#organization_id",
        "organization_name": "#organization_name",
        "workspace_id": "#workspace_id",
        "workspace_name": "#workspace_name",
        "workspace_last_user": "#workspace_last_user",
        "reporting_group_id": "#workspace_reporting_group_id",
        "reporting_group_name": "#workspace_reporting_group_name",
        "alert_name": "#alert_name",
        "alert_information": "#alert_information",
        "alert_start": "#alert_start",
        "alert_element": "#alert_element",
        "timestamp": "#timestamp"
    }
}

Microserviço executado

Variáveis	Descrição
#operation_id	ID da operação executada
#microservice_id	ID do microserviço
#microservice_name	Nome do microsserviço
#operation_startdate	Data e hora de início da operação (ISO 8601)
#operation_enddate	Data e hora de fim da operação (ISO 8601)
#operation_result	Resultado da operação (Completed, Error, Timeout ou Cancelled)
#workspace_id	ID do dispositivo
#workspace_name	Nome do dispositivo
#workspace_last_user	Último usuário que usou o dispositivo
#workspace_reporting_group_id	ID do grupo de relatório
#workspace_reporting_group_name	Nome do grupo de relatório
#operacao_iniciadapor	Usuário ou componente que iniciou a execução do microsserviço

Exemplo de template

{
    "message": {
      "event_type" : "#event_type",
      "organization_id" : "#organization_id",
      "organization_name" : "#organization_name",
      "timestamp" : "#timestamp",
      "workspace_id" : "#workspace_id",
      "workspace_name" : "#workspace_name",
      "workspace_last_user" : "#workspace_last_user",
      "reporting_group_id" : "#workspace_reporting_group_id",
      "reporting_group_name" : "#workspace_reporting_group_name",
      "operation_id": "#operation_id",
      "microservice_id": "#microservice_id",
      "microservice_name": "#microservice_name",
      "operation_startdate": "#operation_startdate",
      "operation_enddate": "#operation_enddate",
      "operation_result": "#operation_result"
    }
}

Objeto criado, modificado ou eliminado

Variáveis	Descrição
#event_type	Tipo de evento
#organization_id	ID da organização
#organization_name	Nome da organização/inquilino
#timestamp	Data e hora do evento (ISO 8601)
#entity_type	Tipo de entidade
#entity_name	Nome da entidade
#entity_id	ID da entidade
#action	Ação realizada (Criação, Modificação ou Eliminação)
#triggered_by_name	Nome do usuário que desencadeou o evento
#triggered_by_email	Endereço de email do usuário que desencadeou o evento
#triggered_by_id	ID do usuário que desencadeou o evento

Exemplo de template

{
  "message": {
    "event-type": "#event_type",
    "organization": {
      "id": "#organization_id",
      "name": "#organization_name"
    },
    "entity": {
      "entity-type": "#entity_type",
      "object-name": "#entity_name",
      "object-id": "#entity_id"
    },
    "metadata": {
      "action": "#action",
      "timestamp": "#timestamp",
      "user-name": "#triggered_by_name",
      "useremail": "#triggered_by_email",
      "user-id": "#triggered_by_id"
    }
  }
}

Operação executada

Variáveis	Descrição
#event_type	Tipo de evento
#timestamp	Data e hora do evento (ISO 8601)
#organization_id	ID da organização
#organization_name	Nome da organização/inquilino
#operation_type	Tipo de operação
#description	Descrição da operação
#status	Estado atual da execução da operação
#summary	Resumo da operação (JSON)
#started_by	Usuário que iniciou a operação
#created_at	Data e hora de criação da operação (ISO 8601)
#started_at	Data e hora de início da operação (ISO 8601)
#finished_at	Data e hora de finalização da operação (ISO 8601)
#total_workspaces	Número total de dispositivos processados
#total_warnings	Número total de execuções com advertências durante a operação
#total_errors	Número total de execuções com erros durante a operação
#flow_id	ID do fluxo associado
#microservice_id	ID do microserviço associado
#fra_type	Tipo de Flexxible Remote Assistance (FRA)
#fra_start	Data e hora de início de Flexxible Remote Assistance (FRA) (ISO 8601)
#fra_end	Data e hora de fim de Flexxible Remote Assistance (FRA) (ISO 8601)

Exemplo de template

{
  "message": {
    "event_type": "#event_type",
    "timestamp": "#timestamp",
    "organization": {
      "id": "#organization_id",
      "name": "#organization_name"
    },
    "operation": {
      "type": "#operation_type",
      "description": "#description",
      "status": "#status",
      "summary": "#summary",
      "started_by": "#started_by",
      "created_at": "#created_at",
      "started_at": "#started_at",
      "finished_at": "#finished_at"
    },
    "results": {
      "total_workspaces": "#total_workspaces",
      "total_warnings": "#total_warnings",
      "total_errors": "#total_errors"
    },
    "context": {
      "flow_id": "#flow_id",
      "microservice_id": "#microservice_id",
      "fra_type": "#fra_type",
      "fra_start": "#fra_start",
      "fra_end": "#fra_end"
    }
  }
}

Operação executada em um workspace

Variáveis	Descrição
#event_type	Tipo de evento
#timestamp	Data e hora do evento (ISO 8601)
#organization_id	ID da organização
#organization_name	Nome da organização/inquilino
#operation_type	Tipo de operação
#description	Descrição da operação
#operation_status	Estado da operação
#started_by	Usuário que iniciou a operação
#created_at	Data e hora de criação da operação (ISO 8601)
#started_at	Data e hora de início da operação (ISO 8601)
#finished_at	Data e hora de fim da operação (ISO 8601)
#operation_flow_id	ID do fluxo associado à operação
#operation_microservice_id	ID do microserviço associado à operação
#operation_fra_type	Tipo de Flexxible Remote Assistance (FRA)
#operation_fra_start	Data e hora de início de Flexxible Remote Assistance (FRA)(ISO 8601)
#operation_fra_end	Data e hora de fim de Flexxible Remote Assistance (FRA) (ISO 8601)
#workspace_id	ID do dispositivo
#workspace_name	Nome do dispositivo
#workspace_last_user	Último usuário que usou o dispositivo
#workspace_reporting_group_id	ID do grupo de relatório
#workspace_reporting_group_name	Nome do grupo de relatório
#workspace_operation_result	Resultado da operação no dispositivo
#workspace_operation_startdate	Data e hora de início da operação no workspace (ISO 8601)
#workspace_operation_enddate	Data e hora de finalização da operação no workspace (ISO 8601)

Exemplo de template

{
  "message": {
    "event_type": "#event_type",
    "timestamp": "#timestamp",
    "organization": {
      "id": "#organization_id",
      "name": "#organization_name"
    },
    "operation": {
      "type": "#operation_type",
      "description": "#description",
      "status": "#operation_status",
      "started_by": "#started_by",
      "created_at": "#created_at",
      "started_at": "#started_at",
      "finished_at": "#finished_at"
    },
    "context": {
      "flow_id": "#operation_flow_id",
      "microservice_id": "#operation_microservice_id",
      "fra_type": "#operation_fra_type",
      "fra_start": "#operation_fra_start",
      "fra_end": "#operation_fra_end"
    },
    "workspace": {
      "id": "#workspace_id",
      "name": "#workspace_name",
      "last_user": "#workspace_last_user",
      "reporting_group": {
        "id": "#workspace_reporting_group_id",
        "name": "#workspace_reporting_group_name"
      }
    },
    "execution": {
      "result": "#workspace_operation_result",
      "start_date": "#workspace_operation_startdate",
      "end_date": "#workspace_operation_enddate"
    }
  }
}

Slack

A seguir, mostra-se um exemplo de template compatível com Slack Incoming Webhooks, que pode ser usado como base para construir a mensagem enviada pelo Portal:

{
  "text": "*Flexxible microservice was executed*",
  "blocks": [
    {
      "type": "section",
      "fields": [
        {
          "type": "mrkdwn",
          "text": "*Microservicio:*\n#microservice_name"
        },
        {
          "type": "mrkdwn",
          "text": "*Resultado:*\n#operation_result"
        }
      ]
    },
    {
      "type": "section",
      "fields": [
        {
          "type": "mrkdwn",
          "text": "*Organización:*\n#organization_name"
        },
        {
          "type": "mrkdwn",
          "text": "*Workspace:*\n#workspace_name"
        }
      ]
    },
    {
      "type": "section",
      "fields": [
        {
          "type": "mrkdwn",
          "text": "*Inicio:*\n#operation_startdate"
        },
        {
          "type": "mrkdwn",
          "text": "*Fin:*\n#operation_enddate"
        }
      ]
    }
  ]
}

nota

Para mais informações sobre o formato de mensagens, os blocos disponíveis e as melhores práticas, consulte o guia oficial do Slack.

Microsoft Teams

No Microsoft Teams, os modelos podem ser consultados diretamente nas configurações de cada canal.

nota

Para obter detalhes sobre como configurar corretamente um webhook de entrada e qual estrutura deve ter o modelo JSON, consulte o guia oficial da Microsoft.

Vista de detalhes

Ao selecionar um webhook na tabela, você acessa sua visão de detalhe:

• Visão geral
• Métricas

Visão geral

Apresenta cartões com informações básicas: Estado, Criado em e Atualizado em.

1. Visão geral

• Nome. Nome atribuído ao webhook.
• Tipo de evento. Evento que ativará o webhook.
• Criado por. Usuário que criou o evento.
• Atualizado por. Último usuário que modificou o webhook.
• URL de destino. Endereço do sistema externo que recebe o evento e age conforme a informação provida na mensagem.

2. Recursos selecionados

Mostra os recursos associados conforme o tipo de evento.

3. Modelo de mensagem

Apresenta a estrutura JSON configurada para o webhook.

Métricas

Tentativas de entrega de mensagens

Esta aba apresenta dois níveis de informação. Na parte superior, são mostrados cartões resumo com o estado global das mensagens enviadas através do webhook:

• Mensagens bem-sucedidas
• Mensagens pendentes
• Mensagens em progresso
• Mensagens falhadas
• Total de mensagens
• Taxa de sucesso

Na parte inferior, é mostrada uma tabela com o histórico de tentativas de envio de mensagens correspondentes aos últimos 28 dias. Os registros podem ser filtrados segundo os seguintes critérios: Todas as tentativas, Tentativas bem-sucedidas, Tentativas pendentes, Tentativas falhadas e Tentativas em progresso.

A tabela inclui as seguintes informações:

• Estado. Resultado da execução.
• Duração. Em milissegundos, tempo que levou para executar o webhook.
• Código de resposta. Código HTTP retornado ao executar o webhook.
• Executado em. Data e hora em que se realizou a execução.
• Ações. Abre uma janela com o detalhe da execução.

Quando uma chamada para a URL de destino não é concluída corretamente, o sistema tenta enviar a mensagem novamente de forma automática, conforme a seguinte programação:

• Imediatamente
• Após 5 segundos
• Após 5 minutos
• Após 30 minutos
• Após 2 horas
• Após 5 horas
• Após 10 horas
• Após 10 horas (adicionais)

nota

Cada intervalo começa a partir da falha da tentativa anterior.

informações

Se o envio de uma mensagem falhar três vezes e for concluído com sucesso na quarta tentativa, na tabela serão mostradas quatro tentativas (três falhadas e uma bem-sucedida). No entanto, o sistema contará como uma única mensagem.

Ações sobre webhooks

A visão de detalhe também permite realizar as seguintes ações sobre o webhook:

Habilitar / Desabilitar

Habilita ou desabilita o webhook conforme seu estado atual.

nota

Os webhooks estão desabilitados por padrão.

Editar

Permite modificar:

• Nome
• Tipo de evento
• URL de destino
• Recursos
• Modelo de mensagem

Excluir

Remove o webhook permanentemente. Esta ação não pode ser desfeita.

Testar

Envie uma mensagem com o conteúdo do modelo para a URL configurada sem substituir as variáveis por valores reais. O objetivo dessa ação é validar a conectividade e o formato da mensagem.