Webhooks no Workflow do TOTVS CRM: automação de processos integrada

  WEBHOOKS NO WORKFLOW DO TOTVS CRM

 

Produto:	TCRM - Gestão de Clientes
Linha de Produto:	TOTVS CRM
Segmento:	Cross Segmentos
Módulo:	Workflow
Aplicação	Web/app móvel
Identificador:	ME261020221452
Stakeholder:	TOTVS Connector
Ticket:
Requisito/Story/Issue (informe o requisito relacionado) :	DTCRMSC-2480 - ME261020221452 - Suporte a webhooks via Workflow Em Execução

Muitas empresas enfrentam o desafio de manter seus registros atualizados em diversos sistemas quando uma ação é executada no TOTVS CRM. Esse processo manual é demorado e pode levar a erros, impactando negativamente a eficiência e produtividade da equipe. Para superar essa dificuldade, o TOTVS CRM lançou recentemente um novo recurso de ação chamado Webhook, disponível no módulo de workflow. Com a utilização de Webhooks, os clientes agora podem automatizar esses processos e integrar facilmente diferentes sistemas e aplicativos. Quando um gatilho de criação ou atualização é acionado no TOTVS CRM, a ação de Webhook é executada, permitindo que as informações sejam atualizadas em tempo real em outros sistemas conectados. Esse processo resulta em atualizações rápidas e precisas, economizando tempo e eliminando erros manuais que antes eram muito comuns. Em outras palavras, a ação de Webhook permite que os clientes conectem seus sistemas e automatizem a atualização de registros, o que simplifica o processo e melhora significativamente a eficiência operacional da empresa.

   

Saída: esta integração envia dados do TCRM - Gestão de Clientes para uma ferramenta destino, especificada na configuração.

Esta configuração permite enviar dados do TOTVS CRM para outras ferramentas que disponham de uma URL de entrada de dados. Essa URL precisa conseguir ler e consumir dados enviados em formato JSON.

É importante ter um desenvolvedor ou contato com o suporte do seu outro sistema para checar a compatibilidade com a leitura do pacote de dados que o TOTVS CRM envia.

1. Com o TOTVS CRM Gestão de Clientes aberto em seu navegador, acesse o Workflow por meio do menu principal;


2. Para adicionar uma automação, clique no botão "Adicionar" localizado no canto superior direito da tela;


3. No campo de nome, insira uma breve descrição do Webhook, facilitando a identificação do cadastro em acessos futuros. Se necessário, adicione informações complementares no campo de observações;


4. Depois de nomear seu Workflow, selecione o gatilho do seu workflow clicando no botão "Selecionar Gatilho" disponível em tela. Em seguida, selecione o gatilho que iniciará sua automação clicando no botão "Selecionar Gatilho". O gatilho será o evento que desencadeará a chamada do Webhook, como uma atividade concluída ou uma oportunidade ganha, entre outros;


5. Se desejar, você pode adicionar condições (filtros) para limitar quando a automação será executada, clicando em "Adicionar Condições";


6. Por fim, selecione a ação "Webhook" em "Selecionar Ação" e informe a URL pública do sistema que receberá a notificação do evento. Se necessário, adicione cabeçalhos adicionais para questões técnicas, como autenticação;


7. Salve seu Workflow com o status de ativo e ele passará a ser executado para os próximos eventos;


8. Vale destacar que Webhooks no TOTVS CRM são regidos por algumas características técnicas importantes. Consulte a próxima seção deste documento para maiores informações a respeito, permitindo que sua integração aconteça com sucesso e de forma eficiente.

Quando o TOTVS CRM Gestão de Clientes realiza uma chamada para sistemas externos via Webhooks, ele transmite metadados sobre o evento que permitem identificar o que aconteceu e reagir adequadamente. Esses metadados são enviados por meio de uma chamada HTTP utilizando o método POST, com o conteúdo (payload/body) formatado em JSON.

Aqui está um exemplo desse formato JSON e as informações incluídas nele para referência:

Copiar

    
    {
      "eventId": "00000000-0000-0000-0000-000000000000",
      "timestamp": "2022-05-06T15:28:36.110-03:00",
      "workflow": {
        "id": "00000000-0000-0000-0000-000000000000",
        "description": "Lorem ipsum dolor sit amet"
      },
      "trigger": {
        "id": "00000000-0000-0000-0000-000000000000",
        "description": "Opportunity won"
      },
      "source": {
        "object": {
          "id": "00000000-0000-0000-0000-000000000000",
          "description": "Opportunity",
          "contextUrl": "/api/v11/opportunity/opportunities"
        },
        "row": {
          "id": "00000000-0000-0000-0000-000000000000",
          "externalId": "00000000-0000-0000-0000-000000000000"
        }
      }
    }
    
  

 A tabela abaixo contém informações detalhadas sobre os atributos presentes no formato JSON. Esses atributos são listados juntamente com seus respectivos formatos e intenções. Essas informações podem ser úteis para entender melhor a estrutura do JSON e como usá-lo.

O TOTVS CRM Gestão de Clientes faz a execução das chamadas de forma assíncrona e baseada em consistência eventual, o que pode resultar em eventos entregues fora de ordem e com atrasos de alguns minutos. Em caso de falhas de comunicação, os eventos são retornados para a fila e uma nova tentativa é feita após pelo menos 5 minutos, podendo ocorrer entregas de novos eventos durante esse período. É importante que o sistema terceiro que recebe os eventos esteja preparado para lidar com possíveis cenários de eventos entregues fora de ordem, mais de uma vez e/ou com atrasos, identificáveis pelos atributos eventId e timestamp.

Quando o TOTVS CRM Gestão de Clientes chama o sistema terceiro para informar um evento, ele verifica se a resposta HTTP recebida é da família 2xx para entender se a entrega foi bem-sucedida. Se sim, o evento é considerado entregue com sucesso. Caso contrário, o evento é encaminhado para uma fila de novas tentativas de entrega, com um intervalo de pelo menos 5 minutos entre cada tentativa. Se após 10 tentativas o evento não for entregue com sucesso, ele será descartado. O TOTVS CRM também estabelece um tempo limite de 5 segundos para a conexão com o serviço remoto e 60 segundos para receber uma resposta. Se esses limites forem ultrapassados, o evento será encaminhado para a fila de novas tentativas, independentemente de o sistema terceiro ter recebido a mensagem depois desses limites.