Reactive WebHook¶

Introdução¶

O Reactive WebHook é um sistema que atua na entrega de eventos que emanam dos serviços da Plataforma TOTVS Apps para os serviços externos que se subscreveram a esses eventos. Essa entrega é feita através de uma chamada HTTP POST para o endpoint REST do serviço externo.

No fluxo abaixo, é possível observar o fluxo de entrega de eventos do Reactive WebHook de forma simplificada:

Limitações¶

O Reactive Webhook é um sistema de entrega de eventos, tendo sua origem em aplicações internas da TOTVS e destino aplicações externas, a entrega é realizada por meio de uma requisição POST para uma URL cadastrada na subscrição.

A intenção do Reactive WebHook é promover a integração assíncrona¹ e reativa² entre os serviços da TOTVS com serviços externos através de eventos. Por esse motivo, é recomendado que os serviços externos não executem processamentos complexos e demorados ao receber esses eventos. Assim, implemente um processamento assíncrono que não bloqueie o recebimento dos eventos enviados pelo Reactive WebHook.

APIs¶

Para explorar a documentação detalhada da REST API é necessário clicar aqui.

Tutoriais¶

Como realizar a autenticação e obter um token de acesso temporário?¶

Para se autenticar é necessário realizar os seguintes passos:

1. Obter as Credenciais de acesso: client_id e client_secret;

   Essas credenciais de acesso são fornecidas pela TOTVS através da central de suporte de cada produto.

2. Com as credencias de acesso, realizar a seguinte chamada para obter o token de acesso temporário:

   1 2 3 4 5 6 7

   curl \ --location 'https://totvsapp.rac.totvs.app/totvs.rac/connect/token' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --data-urlencode 'grant_type=client_credentials' \ --data-urlencode 'client_id=<seu_client_id>' \ --data-urlencode 'client_secret=<seu_client_secret>' \ --data-urlencode 'scope=authorization_api'

   O token de acesso temporário virá no corpo da resposta, no atributo access_token. token virá no corpo da resposta, no atributo access_token, conforme exemplo abaixo:

   1 2 3 4 5

   { "access_token": "<token>" <!-- token de acesso temporário -->, "expires_in": 1200 <!-- tempo de expiração -->, "token_type": "Bearer" <!-- tipo de token --> }

3. Com o token de acesso temporário é possível chamar qualquer API do Reactive Webhook passando o token no cabeçalho Authorization, da seguinte forma:

   1 2 3 4

   curl \ --location 'https://reactive-webhook.dev.totvs.app/v1/available-event-types' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer <token>'

Como consultar a lista de eventos disponíveis?¶

Para listar os eventos é necessário realizar os seguintes passos:

1. Realizar a autenticação;

2. Realizar chamada à API de lista de eventos disponíveis, da seguinte forma:

   1 2 3 4 5

   curl \ --location 'https://reactive-webhook.dev.totvs.app/v1/available-event-types' \ -X 'GET' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer <token>'

3. O retorno será a lista de eventos disponíveis (eventType e exchangeId), conforme exemplo abaixo:

   1 2 3 4 5 6 7 8 9 10 11 12

   { "page": 1, <!-- página atual, começando com 1 --> "pageSize": 10, <!-- tamanho da página --> "hasNext": true, <!-- indicação se tem próxima página --> "items": [ { "eventType": "Evento1", "exchangeId": "exchange1", "identification": "<id>" }, ... }

Como se subscrever em um evento do Reactive WebHook?¶

Para se subscrever em um evento é necessário realizar os seguintes passos:

1. Realizar a autenticação - O token de acesso temporário contextualiza os eventos que serão exibidos;

2. Nome da exchange e do evento que será assinado, obtido através da API de consulta de eventos.

3. Realizar chamada à API de subscrição, da seguinte forma:

   1 2 3 4 5 6 7 8 9 10 11 12 13

   curl \ --location 'https://reactive-webhook.dev.totvs.app/v1/subscription' \ -X 'POST' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer <token>' \ --data '{ "exchangeId": "<exchange-do-evento>", "eventType": "<nome-do-evento>", "responseEndpoint": "<callback>", <!-- endereço que receberá o evento --> "responseHttpHeaders": {}, <!-- cabeçalhos que serão enviados junto com o evento, é possível colocar cabeçalhos de autenticação (Ex.: HTTP Basic Auth) --> "tries": 1, <!-- quantidade de retentativas antes de enviar o evento para a dead letter--> "timeout": 1000 <!-- Tempo máximo de espera em cada tentativa--> }'

   !!! tip "Dica" É recomendado utilizar o campo responseHttpHeaders para passar os cabeçalhos de autorização HTTP.

Dúvidas frequentes¶

É aconselhável retornar um erro ou exceção diretamente ao Webhook após a validação do evento?¶

Não é aconselhavel fazer isso, visto que o Reactive Webhook age apenas como o canal de entrega do evento. Recomenda-se que a validação seja realizada internamente em um processo desacoplado do recebimento de eventos, como descrito neste trecho.

Como devo validar os eventos que chegam do Reactive Webhook?¶

É crucial separar a validação dos eventos do processo de entrega. Realizar validações durante a entrega pode reter o serviço do Webhook, causando atrasos em eventos subsequentes. É preciso efetuar essas validações em um estágio posterior, internamente, para garantir a eficiência e a fluidez do serviço.

Pode-se usar uma fila de processamento ou, até mesmo, um banco de dados para isso.

Caso haja problemas nesse processamento assíncrono em um determinado evento ou caso queira reportar eventos consequentes a um determinado evento recebido, os serviços da Plataforma TOTVS Apps fornecerão outros canais de integração para que essas mensagens possam ser publicadas.

Se minha API, serviço ou URL estiver offline e o Webhook não conseguir entregar o evento, o que acontece?¶

Na API de subscrição, o Reactive Webhook permite que sejam configuradas regras de retentativas (retries) e de tempo máximo de espera (timeout). Assim, o Reactive Webhook realizará as N tentativas configuradas em cada subscrição respeitando o tempo máximo de espera de cada tentativa.

Ao atingir o limite máximo de tentativas (configurado na sua subscrição), o evento será enviado para a Dead Letter.

Posso consultar quais eventos foram para Dead Letter?¶

Sim, existe uma rota específica para essa finalidade. Pode-se encontrar detalhes sobre como consultar os eventos na Dead Letter na documentação da API.

É possível que o Webhook reprocessse os eventos armazenados na Dead Letter?¶

Não, os eventos armazenados na Dead Letter não retornam ao fluxo do Webhook. Para reprocessar esses eventos, é necessário consumir a rota da Dead Letter e realizar o processamento internamente.

É possível listar os eventos disponíveis?¶

Sim, na API de Eventos Disponíveis (available-event-tyoes). Porém é um requisito conhecer o nome da exchange e o nome do evento que se deseja escutar. Cada aplicação interna da TOTVS pode emitir diversos tipos de evento em diversas exchanges.

É necessário entrar contato com a TOTVS para saber os eventos mais adequados para cada contexto.