Webhooks Introdução Webhook é um método de comunicação utilizado para que aplicativos e sistemas se comuniquem em tempo real de forma reativa e acontece sempre que um evento específico ocorre em uma das aplicações. Para exemplificar o uso de webhooks, imagine que, a cada produto cadastrado, atualizado ou excluído no Bling, seja necessário realizar a mesma operação em outro sistema. Em vez de criar uma rotina que periodicamente consulte a API do Bling para verificar alterações, é possível configurar webhooks para que sejam acionados automaticamente a cada uma dessas ações. Dessa forma, o sistema receberá os dados em tempo real, processará as informações necessárias e evitará o uso de rotinas automáticas que demandem consultas constantes ao Bling. Como cadastrar

1. Acesse o aplicativo já cadastrado.
2. Certifique-se que o aplicativo possua os escopos referentes aos recursos aos quais queira ser notificado. Caso o aplicativo não possua um escopo específico, o recurso de webhook correspondente não será exibido para configurar.
3. Navegue até a aba "Webhooks".

4. Configure os servidores que receberão os eventos.

5. Configure os recursos que deseja receber as notificações.

• Selecione o servidor que deseja receber o evento.
• Marque as ações que deseja ser notificado.
• Selecione a versão do payload conforme a estrutura de retorno.

6. Salve as alterações.

Recebimento de eventos O aplicativo começará a receber os eventos após a obtenção dos tokens de acesso do usuário ao final do fluxo de autorização. Webhooks vs Polling Atualização de informações Webhooks e polling são duas técnicas amplamente utilizadas para integração de sistemas e comunicação entre aplicações. Ambos os métodos têm como objetivo transferir informações entre sistemas, mas funcionam de maneira fundamentalmente diferente. A escolha entre webhooks e polling depende do caso de uso, das demandas de desempenho e das restrições do sistema. Webhooks Webhooks são uma abordagem baseada em eventos, onde um servidor é configurado para enviar notificações para outro sistema sempre que um determinado evento ocorre. Isso é feito através de requisições HTTP para um endpoint previamente definido. O uso de webhooks reduz a sobrecarga de requisições desnecessárias, enviando apenas quando há dados novos. Polling Polling é uma técnica onde um sistema consulta periodicamente o servidor de origem para verificar se há novos dados ou atualizações. Nesse modelo, o cliente faz requisições repetitivas, independentemente de haver ou não dados novos. Em relação ao webhook, é menos eficiente, visto que podem ser realizadas muitas requisições sem dados novos. Autenticação Técnica A autenticação das mensagens enviadas pelo Bling deve ser realizada por meio do cabeçalho HTTP X-Bling-Signature-256. Esse cabeçalho contém um hash de autenticação HMAC (Hash-Based Message Authentication Code) composto pelo payload JSON da resposta e o client secret do aplicativo. Esse processo garante a integridade e a autenticidade dos dados enviados pelo Bling. Validação do hash Para garantir que a mensagem recebida é legítima e não foi manipulada, considere os seguintes passos:

1. Gerar um hash HMAC utilizando o payload e o client secret do aplicativo.
2. Comparar se o hash informado no header X-Bling-Signature-256 é igual ao hash gerado.

Exemplo de hashes:

• Hash gerado: a012da891d0cebcb375c8e12b881e81df40256dfffc25e08ba9db4ab35515516
• Header informado na requisição: sha256=a012da891d0cebcb375c8e12b881e81df40256dfffc25e08ba9db4ab35515516

Observações:

• O Bling usa um código hash hexadecimal HMAC para calcular o hash.
• A assinatura do hash sempre começa com sha256=.
• O padrão de codificação utilizado é o UTF-8.

Idempotência Idempotência é a capacidade de uma operação retornar o mesmo resultado, independentemente de quantas vezes seja executada, desde que os parâmetros sejam os mesmos. No contexto de webhooks, caso o Bling envie o mesmo webhook duas vezes, sua aplicação deve responder a ambas as requisições com um código HTTP 2xx. Entrega não ordenada Não há garantia da entrega dos eventos na ordem em que foram gerados. Por exemplo, um webhook de atualização de produto pode ser recebido antes que o webhook de criação deste mesmo produto. Uma prática recomendada para lidar com esse cenário é gerenciar os webhooks recebidos de maneira assíncrona, usando filas, por exemplo. Retentativas O processo de retentativas foi projetado para garantir a entrega confiável de webhooks aos integradores, mesmo diante de falhas temporárias no sistema de destino. Serão feitas tentativas no período máximo de 3 dias onde, a cada retentativa, o tempo da próxima retentativa poderá ser maior. Ao final do processo de retentativas, caso o processamento do evento continue com problemas, a configuração do webhook para o recurso em questão será desabilitada e o Bling não enviará novos eventos até que a configuração seja habilitada manualmente através das configurações de webhooks do aplicativo. Uma requisição é considerada entregue com sucesso quando o integrador responde com um código HTTP 2xx em até 5 segundos. Caso exceda o tempo de resposta ou o código for diferente de 2xx serão feitas as retentativas no envio da mensagem. Ações Abaixo estão detalhadas as ações disponíveis:

• created: Ocorre quando um recurso é criado.
• updated: Ocorre quando um recurso é atualizado.
• deleted: Ocorre quando um recurso é deletado definitivamente.
  • Alterar a situação de um recurso para excluído gera um evento de updated.

Recursos Recursos disponíveis Antes de configurar um recurso de webhook, é necessário adicionar o escopo referente ao recurso aos dados básicos do aplicativo.

• Pedido de Venda: order
• Produto: product
• Estoque: stock
• Estoque virtual: virtual_stock
• Produto fornecedor: product_supplier
• Nota fiscal: invoice
• Nota fiscal de consumidor: consumer_invoice

O webhook de Estoque Virtual é ativado automaticamente quando o de Estoque é habilitado, por esse motivo, herdará suas configurações. Diferenças entre eventos de estoque e estoque virtual Os payloads não são as únicas diferenças entre os eventos. Os gatilhos também variam:

• Eventos de estoque são disparados apenas por lançamentos físicos, ou seja, lançamentos de estoque por vendas, NF-es, tela de estoque, etc.
• Eventos de estoque virtual são disparados por reservas de vendas e atualização de saldo em produtos com composição e tipo de estoque virtual.

Estrutura de retorno Detalhamento dos campos:

• eventId: Identificador único do evento.
• date: Data no formato ISO 8601.
• version: Versão do webhook.
• event: Recurso junto a ação separados por ".".
• companyId: ID da empresa.
  • Para obtê-lo, consulte os dados básicos da empresa por API.
• data: Payload do evento.

Considere:

• $resource: O recurso do webhook.
• $action: A ação do webhook.
• $payload: Uma das estruturas abaixo, conforme o recurso e a ação do webhook.

Pedido de venda Estrutura dos payloads dos webhooks de pedido de venda: Versão 1 Produto Estrutura dos payloads dos webhooks de produto: Versão 1 Estoque Estrutura dos payloads dos webhooks de estoque: Versão 1 Estoque Virtual Estrutura do payload do webhook de estoque virtual: Versão 1 O campo vinculoComplexo indica que o produto possui mais de 200 produtos vinculados (componentes ou composições) que tiveram seu estoque virtual atualizado e seus saldos devem ser obtidos através da API. Estoque Virtual Estrutura do payload do webhook de estoque virtual: Versão 1 O campo vinculoComplexo indica que o produto possui mais de 200 produtos vinculados (componentes ou composições) que tiveram seu estoque virtual atualizado e seus saldos devem ser obtidos através da API. Produto fornecedor Estrutura dos payloads dos webhooks de produto fornecedor: Versão 1 Nota fiscal eletrônica e de consumidor Estrutura dos payloads dos webhooks de nota fiscal eletrônica e de consumidor: Versão 1 Exemplo de retorno Para exemplicicar, conforme a estrutura de retorno, em uma ação de atualização no recurso de produtos, teríamos o seguinte payload: