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.
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:
{
"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.
Atributo
|
Tipo de dados
|
Descrição
|
---|---|---|
eventId | String | Identificador único do evento |
timestamp | Data e hora formatados como String (ISO 8601) | Data e hora em que o Workflow foi executado |
workflow.id | UUID formatado como String | Identificador único do workflow que emitiu o evento |
workflow.description | String | Nome do workflow que emitiu o evento, como definido no momento que a chamada foi disparada |
trigger.id | UUID formatado como String | Identificador único global do gatilho definido no Workflow no momento que o evento foi disparado |
trigger.description | String | Nome do gatilho definido no Workflow no momento que o evento foi disparado |
source.object.id | UUID formatado como String | Identificador único do objeto de origem do evento (oportunidades, leads, atividades, etc) |
source.object.description | String | Descrição do objeto de origem do evento |
source.object.contextUrl | URL formata como String | URL base da API do objeto de origem no TOTVS CRM Gestão de Clientes |
source.row.id | UUID formatado como String | Identificador único do registro de origem do evento (ID da oportunidade, lead, atividade, etc) |
source.row.externalId | String | Identificador externo do registro de origem do evento, se houver um e o atributo estiver visível no Workflow |
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.