Webhooks

Webhooks é uma maneira de integrar dois sistemas diferentes de forma que eventos sejam enviados entre eles quando determinadas ações são feitas, permitindo que essa integração possa reagir a eles com o intuito de automatizar processos de negócio de acordo com o conjunto de regras definidas nessa integração.

No TOTVS CRM Gestão de Clientes, Webhooks podem ser utilizados para receber esses eventos em seus aplicativos ou sistemas terceiros sempre que, por exemplo, uma conta for criada ou modificada, uma oportunidade for ganha ou perdida ou um pedido de venda foi finalizado.

No TOTVS CRM Gestão de Clientes, os Webhooks funcionam através do módulo Workflow. Os passos necessários para criar a integração, portanto, são muito similares a aqueles para a criação de um Workflow automatizado:

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 direto da tela.
3. No campo de nome, informe uma rápida descrição sobre o Webhook que você está criando, facilitando a identificação do cadastro em acessos futuros. Se precisar de uma descrição longa complementar, você também pode utilizar o 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. O gatilho será o evento que irá iniciar a sua automação e, portanto, a chamada do Webhook, e ele pode ser um item como uma atividade concluída, uma oportunidade ganha e outros mais. 
5. Uma vez selecionado o gatilho, você pode opcionalmente informar condições (filtros) para a sua automação, limitando em que momentos ele será executado. Isso pode ser feito clicando em ADICIONAR CONDIÇÕES exibido após a seleção do gatilho.
6. Por fim, clique em SELECIONAR AÇÃO e depois em WEBHOOK para configurar os dados do sistema que receberá o evento notificando da ação feita no TOTVS CRM Gestão de Clientes. Você deverá informar a URL pública que o seu sistema disponibiliza para que o TOTVS CRM faça as chamadas de notificação, bem como cabeçalhos adicionais opcionais caso eles sejam necessários 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.

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.

Formato de comunicação dos Webhooks

O TOTVS CRM Gestão de Clientes, ao efetuar uma chamada para sistemas terceiros via Webhooks, irá repassar alguns metadados a respeito do evento que permitem, dentre outros, identificar o que aconteceu e reagir de acordo.

Esse repasse acontece através de uma chamada HTTP por meio do verbo POST, com conteúdo (payload/body) formatado em JSON. Um exemplo desse JSON e as informações presentes nele estão disponíveis a seguir.

{
  "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 a seguir detalha os atributos presentes no JSON, incluindo seus respectivos formatos e intuitos.

Estratégia da execução das chamadas 

O TOTVS CRM Gestão de Clientes fará o melhor esforço para entregar os eventos de forma ordenada e o mais breve possível. Entretanto, para permitir que cenários de falha sejam tratados de acordo, bem como escalabilidade do produto, não é possível garantir que essa ordenação e entrega rápida aconteça sempre. Ou seja, a chamada dos Webhooks é feita de forma assíncrona, baseada em consistência eventual.

Um cenário de exemplo em que isso pode acontecer é quando há uma falha de comunicação durante a chamada do Webhook, seja por que o sistema terceiro estava offline ou sobrecarregado no momento da chamada ou por que o TOTVS CRM estava passando por dificuldades momentâneas. Quando isso acontecer, o TOTVS CRM irá retornar o evento para a fila de execução e efetuar uma nova tentativa após pelo menos 5 minutos. Caso a instabilidade seja sanada e novos eventos foram produzidos durante esse período, esses eventos poderão ser entregues antes do término do período de espera do evento anterior que foi estacionado.

Ou seja, eventos podem ser entregues fora de ordem, mais de uma vez e/ou com um atraso de vários minutos após a ocorrência da ação dentro do Gestão de Clientes. O sistema terceiro que irá receber esses eventos deve ser capaz de tratar tais cenários, identificáveis através dos atributos eventId (para os cenários em que um evento foi entregue mais de uma vez) e timestamp (para identificação da ordem de emissão dos eventos).

Cenários de falha e como o TOTVS CRM interpreta a resposta do sistema terceiro

Quando o sistema terceiro é chamado para informar de um evento, o TOTVS CRM Gestão de Clientes irá interpretar o status da resposta HTTP dada pelo sistema para entender se o evento foi entregue com sucesso. Desta forma, se o status HTTP recebido for da família 2xx (200 OK, 204 No Content, 202 Accepted, etc), o Gestão de Clientes assumirá que a entrega aconteceu com sucesso e não irá executar novas tentativas para aquele evento.

Entretanto, quando a resposta remota não for da família 2XX (como 404 Not Found, 503 Temporarily Unavailable, 500 Internal Server Error, etc), essa resposta será interpretada como uma falha ao receber o evento e ele será encaminhado para a fila de novas tentativas de entrega. Uma vez nessa fila, o evento ficará estacionado por pelo menos 5 minutos entre uma tentativa de entrega e outra e, após 10 tentativas (incluindo a primeira, antes de entrar na fila), o evento será descartado sem que uma entrega com sucesso seja feita. 

Além do status da resposta HTTP, o TOTVS CRM também aplica a estratégia de timeout (tempo limite) na execução das chamadas HTTP dos Webhooks. Serão utilizados 5 segundos de timeout para a conexão com o serviço remoto (iniciar a chamada remota e a conexão ser estabelecida com sucesso com o servidor) e 60 segundos de timeout para que uma resposta seja recebida. Caso esses tempos limites sejam ultrapassados, o Gestão de Clientes irá interpretar que houve uma falha na chamada e encaminhar o evento para a fila de novas tentativas, como descrito acima, mesmo que o sistema terceiro tenha recebido essa mensagem e concluiu o processamento depois desses 60 segundos de espera máxima.