O que são webhooks e por que utilizá-los?

O webhook, também conhecido como gatilho, é um recurso importante na conexão de sistemas de informação, especialmente na utilização de APIs. Na prática, trata-se de uma notificação ativa realizada pela API para informar ao seu sistema sobre um evento que aconteceu, sem a necessidade de realizar uma consulta ativa, ou seja, ao falarmos da API Focus NF-e, em vez de realizar uma verificação sobre um documento fiscal enviado anteriormente, nós te informaremos de forma ativa quando ocorrer uma modificação. Em outras palavras, estamos considerando uma significativa economia de recursos computacionais ao avisá-lo imediatamente, mas somente quando necessário, sobre a alteração de status de uma nota fiscal.  

Polling vs Webhook

A Focus NF-e possibilita que os usuários de nossos sistemas realizem a consulta ativa de suas requisições, mas também disponibilizamos a opção de cuidarmos disso para você. Nesse ponto, estamos oferecendo a possibilidade de consultas a partir do seu sistema (polling) ou avisos automatizados e pré-programados que serão executados por nós (webhooks).

A maior diferença aqui, está na economia de recursos, especialmente em tempo e processamento computacional. Considere que a maior parte dos modelos de notas fiscais é autorizado sob o regime assíncrono, ou seja, é necessário enviar, aguardar e depois consultar. Isso implica em diversos fatores e etapas que determinam se um documento será processado muito rápido ou não. Desta forma, ao desconhecer exatamente sobre o processamento da nota fiscal, é necessário que busque entender a dinâmica de processamento, a escalabilidade, especialmente com grandes volumes, e como lidará com tudo isso. Consultar ativamente (polling) nem sempre é a melhor escolha. Na verdade, consideramos que isso é desnecessário e, por esse motivo, oferecemos a notificação imediata realizada por nós (webhook), sempre que houver um evento que modifique o status de um documento fiscal.

Boas práticas no recebimento de webhooks

Quando optar pela notificação realizada a partir dos nossos webhooks, considere em primeiro lugar a segurança. Dessa forma, recomendamos que utilize o “authorization_header” que faz parte do cabeçalho e permite a inserção de um token criado por você para identificar nossas requisições de forma segura. Significa, em outras palavras, que sua aplicação reconhece a origem e sabe que é a Focus NF-e que está acionando seu servidor.
Da mesma forma, é interessante que seu serviço nos responda adequadamente, transmitindo um HTTP Code 2xx para sabermos que recebeu nosso webhook. Do contrário, tentaremos mais algumas vezes notificá-lo sobre a ocorrência de algum evento no documento fiscal. Fazemos isso de forma escalada, aumentando o intervalo até desistirmos, mas somente se não tivermos a certeza que recebeu a informação. Para mais detalhes, consulte a nossa documentação técnica aqui.