Webhooks - Documentación de Flexxible

Webhooks é uma funcionalidade que permite integrar a plataforma com ferramentas de terceiros para o envio de notificações quando ocorrem determinados eventos na organização. Eventos disponíveis:

Alerta ativado
Microsserviço executado
Objeto criado
Objeto modificado
Objeto excluído
Operação executada
Operação executada em um workspace

Quando ocorre um desses eventos, a plataforma realiza uma chamada HTTP à URL configurada pela organização e envia uma mensagem com as informações correspondentes. A aplicação de destino pode usar esses dados para executar ações como criar um ticket em um sistema ITSM, enviar uma mensagem pelo Slack ou Microsoft Teams, enviar um e-mail, entre outros. Esta ferramenta só pode ser configurada por um usuário com função de Administrador da organização.

Visão geral

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

Nome. Nome atribuído ao webhook. Ao clicar acessa-se 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 atua conforme as informações fornecidas na mensagem.
Status. Indica se o webhook está Habilitado ou Desabilitado.

Criar uma integração webhook

Para criar um novo webhook devem-se seguir os seguintes passos:

Acessar Configuração → Integrações Webhook.
Clicar em Novo.
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 atua conforme as informações fornecidas na mensagem.

Elementos

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

Alerta ativado
- Mostra a listagem de alertas ativos da organização para selecionar quais enviarão o webhook.
- Enviar webhook para todos os alertas - Ativa o webhook para todos os alertas.
Microsserviço executado
- Mostra a listagem de microsserviços habilitados para selecionar quais enviarão o webhook.
- Enviar webhook para todos os microsserviços - Ativa o webhook para todos os microsserviços.
- Em ambos os casos, o botão Ver permite acessar a visão de detalhe do recurso.
Objeto criado, Objeto modificado ou Objeto excluído
- Mostram uma listagem 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 listagem para selecionar a operação que enviará o webhook quando for executada.
- Enviar webhook para todas as operações - Ativa o webhook para todas as operações.
Operação executada em um workspace
- Mostra uma listagem para selecionar a operação que enviará um webhook para cada dispositivo em que foi executada.
- Enviar webhooks para todas as operações executadas em cada workspace - Ativa o webhook para todas as operações por dispositivo.
- 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 geradas:
  - Uma notificação webhook do tipo Operação executada.
  - Três notificações webhook do tipo Operação executada em um workspace.

Configuração da mensagem

Nesta seção é definida a mensagem que será enviada quando o evento ocorrer. A configuração utiliza 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 o evento ocorre.

Clicar em Salvar.

Uma organização não deveria ter dois webhooks com a mesma configuração porque poderia 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/locatário
#timestamp	Data e hora do evento (ISO 8601)

Alerta ativado

Variáveis	Descrição
#alert_name	Nome do alerta
#alert_information	Informações adicionais do alerta
#alert_start	Data e hora de início do alerta (ISO 8601)
#alert_element	Elemento que disparou o alerta
#workspace_id	ID do workspace
#workspace_name	Nome do workspace
#workspace_last_user	Último usuário que usou o workspace
#workspace_reporting_group_id	ID do grupo de relatório
#workspace_reporting_group_name	Nome do grupo de relatório
#workspace_internal_id	Workspace internal ID

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"
    }
}

Microsserviço executado

Variáveis	Descrição
#operation_id	ID da operação executada
#microservice_id	ID do microsserviç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 término da operação (ISO 8601)
#operation_result	Resultado da operação (Completed, Error, Timeout ou Cancelled)
#workspace_id	ID do workspace
#workspace_name	Nome do workspace
#workspace_last_user	Último usuário que usou o workspace
#workspace_reporting_group_id	ID do grupo de relatório
#workspace_reporting_group_name	Nome do grupo de relatório
#operation_startedby	Usuário ou componente que iniciou a execução do microsserviço
#workspace_internal_id	Workspace internal ID

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 excluído

Variáveis	Descrição
#event_type	Tipo de evento
#organization_id	ID da organização
#organization_name	Nome da organização/locatário
#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 Exclusão)
#triggered_by_name	Nome do usuário que disparou o evento
#triggered_by_email	Endereço de e-mail do usuário que disparou o evento
#triggered_by_id	ID do usuário que disparou 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/locatário
#operation_type	Tipo de operação
#description	Descrição da operação
#status	Status 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 workspaces processados
#total_warnings	Número total de execuções com avisos 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 microsserviço associado
#fra_type	Tipo de Flexxible Remote Assistance (FRA)
#fra_start	Data e hora de início do Flexxible Remote Assistance (FRA) (ISO 8601)
#fra_end	Data e hora de término do 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/locatário
#operation_type	Tipo de operação
#description	Descrição da operação
#operation_status	Status 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 término da operação (ISO 8601)
#operation_flow_id	ID do fluxo associado à operação
#operation_microservice_id	ID do microsserviço associado à operação
#operation_fra_type	Tipo de Flexxible Remote Assistance (FRA)
#operation_fra_start	Data e hora de início do Flexxible Remote Assistance (FRA)(ISO 8601)
#operation_fra_end	Data e hora de término do Flexxible Remote Assistance (FRA) (ISO 8601)
#workspace_id	ID do workspace
#workspace_name	Nome do workspace
#workspace_last_user	Último usuário que usou o workspace
#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 workspace
#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)
#workspace_internal_id	Workspace internal ID

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 utilizado como base para construir a mensagem enviada a partir da plataforma:

{
  "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"
        }
      ]
    }
  ]
}

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 templates podem ser consultados diretamente a partir da configuração de cada canal.

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

Visão de detalhe

Ao selecionar um webhook a partir da tabela acessa-se sua visão de detalhe:

Visão geral
Métricas

Visão geral

Apresenta cartões com informações básicas: Status, 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 atua conforme as informações fornecidas na mensagem.

2. Recursos selecionados

Mostra os recursos associados conforme o tipo de evento.

3. Template 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 status global das mensagens enviadas mediante o webhook:

Mensagens bem-sucedidas
Mensagens pendentes
Mensagens em progresso
Mensagens falhas
Total de mensagens
Índice 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 conforme os seguintes critérios: Todas as tentativas, Tentativas bem-sucedidas, Tentativas pendentes, Tentativas falhas e Tentativas em progresso. A tabela inclui as seguintes informações:

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

Quando uma chamada à URL de destino não é completada corretamente, o sistema tenta reenviar a mensagem de forma automática, conforme a seguinte programação:

Imediatamente
Em 5 segundos
Em 5 minutos
Em 30 minutos
Em 2 horas
Em 5 horas
Em 10 horas
Em 10 horas (adicionais)

Cada intervalo se inicia a partir da falha da tentativa anterior.

Se o envio de uma mensagem falha três vezes e é completado com sucesso na quarta tentativa, na tabela serão mostradas quatro tentativas (três falhas e uma bem-sucedida). No entanto, o sistema o contabilizará 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 status atual.

Os webhooks estão desabilitados por padrão.

Editar

Permite modificar:

Nome
Tipo de evento
URL de destino
Recursos
Template de mensagem

Excluir

Exclui o webhook de forma permanente. Esta ação não pode ser desfeita.

Testar

Envia uma mensagem com o conteúdo do template à URL configurada sem substituir as variáveis por valores reais. O objetivo desta ação é validar a conectividade e o formato da mensagem.

​Visão geral

​Criar uma integração webhook

​Variáveis disponíveis para a mensagem

​Todos os tipos de eventos

​Alerta ativado

​Exemplo de template

​Microsserviço executado

​Exemplo de template

​Objeto criado, modificado ou excluído

​Exemplo de template

​Operação executada

​Exemplo de template

​Operação executada em um workspace

​Exemplo de template

​Slack

​Microsoft Teams

​Visão de detalhe

​Visão geral

​1. Visão geral

​2. Recursos selecionados

​3. Template de mensagem

​Métricas

​Tentativas de entrega de mensagens

​Ações sobre webhooks

​Habilitar / Desabilitar

​Editar

​Excluir

​Testar

Visão geral

Criar uma integração webhook

Variáveis disponíveis para a mensagem

Todos os tipos de eventos

Alerta ativado

Exemplo de template

Microsserviço executado

Exemplo de template

Objeto criado, modificado ou excluído

Exemplo de template

Operação executada

Exemplo de template

Operação executada em um workspace

Exemplo de template

Slack

Microsoft Teams

Visão de detalhe

Visão geral

1. Visão geral

2. Recursos selecionados

3. Template de mensagem

Métricas

Tentativas de entrega de mensagens

Ações sobre webhooks

Habilitar / Desabilitar

Editar

Excluir

Testar