🔔 O que é Webhook?

Webhook é um mecanismo que permite a comunicação entre aplicações web, onde são enviados dados do Servidor para o cliente com base em eventos ocorridos.
Ou seja, um gatilho de notificação automática é enviada quando há ocorrência de eventos em um documento, fornecedores ou outras entidades gerenciadas pela plataforma Líber, evitando a necessidade de consultas recorrentes para atualização no ERP do parceiro.

O envio das mensagens de webhooks é feito imediatamente após a finalização do processamento do evento. Em caso de falha de entrega, é realizado uma nova tentativa de entrega. São realizadas até 6 tentativas, havendo um período de espera entre cada tentativa.

Caso todas as tentativas de entrega falhem e um endereço de e-mail para notificação tenha sido cadastrado, um e-mail será enviado informando que o evento não pode ser entregue.

❗ Ao implementar um serviço para executar os eventos Webhook, é necessário garantir que os serviços são idempotentes, ou seja, que o serviço será capaz de lidar corretamente com múltiplas entregas de um mesmo evento.

🔔 Implementando Webhooks

O envio de Webhook é uma operação parcialmente assíncrona. O Sacado receberá através de um servidor de comunicação (RabbitMq por exemplo) os status e negociações dos títulos. Ao implementar um serviço para escutar os eventos Webhook é necessário garantir que os serviços são idempotentes, ou seja, que o serviço será capaz de lidar corretamente com múltiplas entregas de um mesmo evento.

A implementação do Webhook consiste em uma URL previamente cadastrada pelo usuário, esta URL receberá requisições HTTPS notificando a ocorrência de eventos determinados nos títulos, fornecedores e outras entidades gerenciadas pela Plataforma Liber Capital.

Informações sobre o evento ocorrido são enviadas no payload e nos headers da requisição.
Em caso de falha de entrega por status code 3xx, 4xx ou 5xx, uma nova tentativa de entrega será realizada. São realizadas até 6 tentativas de entrega, havendo um período de espera entre cada tentativa. Caso todas as tentativas de entrega falhem e um endereço de email para notificação tenha sido cadastrado, um e-mail será enviado informando que o evento não pode ser entregue.

🔔 Formato geral do corpo de uma notificação de Webhook

Para facilitar a integração com os webhooks, o payload das requisições possui uma estrutura padrão (envelope) com os seguintes campos principais:

event_type: identifica o tipo do evento.\
event_timestamp: define a ordem cronológica dos eventos.\

Os dados específicos do evento (ou das entidades envolvidas) são incluídos no payload, representado como um objeto JSON com estrutura variável conforme o tipo de evento.

A seguir, é apresentada a descrição OpenAPI do payload genérico. Para detalhes do evento purchase_order.available, Informações específicas do payload do webhook purchase_order.available podem ser encontradas nesta documentação na sessão para Desenvolvedores: Webhook

WebhookNotificationBody:
  type: object
  properties:
    event_timestamp:
      type: string
      format: date-time
      description: Data do evento (RFC 3339)
    event_type:
      type: string
      description: Tipo do evento (ex: "purchase_order.available")
    payload:
      type: object
      description: Dados específicos do evento

Idepotência e Ordenação

O serviço consumidor deve ser idempotente, ou seja, capaz de processar múltiplas notificações do mesmo evento sem efeitos colaterais.
A ordem das notificações não é garantida: eventos A e B podem chegar fora de ordem, mesmo que A tenha ocorrido antes de B.

Recomendações de Processamento

Para eventos relacionados a uma mesma entidade (ex: um título), recomenda-se os Critérios de ordenação e descarte de notificações para webhooks sempre mantendo o rastro do valor de $event_timestamp$ mais recente recebida para cada entidade. O serviço deve, então, comparar esse valor com o valor de event_timestamp recebido em cada nova notificação, descartando a notificação e não realizando o seu processamento caso o evento na nova notificação seja anterior ao último evento processado, conforme abaixo:

Armazenar o event_timestamp mais recente processado por entidade.
Comparar esse timestamp com o da nova notificação.
Ignorar eventos mais antigos para evitar sobrescritas ou inconsistências.