Introdução
Webhooks são recursos que permitem que dois sistemas (ou aplicações) se comuniquem entre si em tempo real quando um evento acontece, sem que nenhuma ação externa precise ser realizada no momento da comunicação.
Em nosso contexto, os Webhooks Catalisa disparam dados (eventos) atualizados aos parceiros, com informações referentes às suas operações.
Desse modo, o parceiro não necessita fazer múltiplas requisições nem desenvolver uma rotina de pesquisa nas APIs, poupando tempo e consumindo menos recursos.
Usar webhooks para obter atualizações em tempo real
Por que usar webhooks
Quando você cria integrações com a Catalisa, seus aplicativos podem precisar receber eventos à medida que ocorrem nos Building Blocks Catalisa para que sistemas de backend executem as ações necessárias.
Para habilitar eventos de webhook, você precisa registrar endpoints de webhook criando uma subscrição. Depois de registrá-los, a Catalisa pode enviar dados de evento em tempo real para o endpoint de webhook do aplicativo quando ocorrem eventos na sua conta Catalisa. A Catalisa usa HTTPS para enviar eventos de webhook ao aplicativo como um conteúdo JSON que inclui um objeto.
O recebimento de eventos de webhook é particularmente útil para ouvir eventos assíncronos, como quando um signatário assina eletronicamente um documento.
Segurança
Para assegurar a procedência das informações recebidas via webhook, todos os eventos enviados pela Catalisa possuem uma assinatura HMAC. A assinatura é gerada a partir de uma chave secreta compartilhada entre a Catalisa e o parceiro.
Ao desenvolver a API para o recebimento de eventos, é necessário que o parceiro adote essa assinatura como meio de validar a origem das informações recebidas.
Somente por meio da assinatura HMAC é possível assegurar que os eventos recebidos são provenientes da Catalisa e garantir a proteção do endpoint do parceiro contra aplicações maliciosas.
Envio de eventos
Os Webhooks Catalisa disparam os eventos para as APIs do parceiro. Se a requisição não for respondida com um código de status de sucesso, o sistema fará três novas tentativas de envio, num intervalo de dois, quatro e seis segundos entre cada tentativa.
Após isso, cessaremos o envio de requisições, e o parceiro poderá utilizar nosso endpoint para nova tentativa.
Circuit Breaker
O Circuit Breaker é um recurso desenvolvido para que o endpoint do parceiro não seja impactado quando ele se encontra indisponível ou quando apresenta lentidão na resposta.
Em qualquer um dos casos, as mensagens enviadas via Webhooks Catalisa entrarão no fluxo do Circuit Breaker e serão entregues quando o sistema do parceiro retornar à normalidade.