# Webhook fiscal > Webhook fiscal é um aviso automático que a plataforma de emissão envia ao sistema da empresa sempre que um documento fiscal muda de situação, como autorização, rejeição ou cancelamento. Em vez de perguntar repetidamente se a nota ficou pronta, o sistema recebe a informação assim que ela acontece, por meio de uma requisição HTTP. **Também conhecido como:** Webhook de documento fiscal, Notificação de status fiscal, Callback fiscal, Webhook de emissão fiscal, Fiscal webhook **Glossário:** [Glossário de A a Z](https://conota.dev/glossario/) · **Letra:** W ## O que é um webhook fiscal, em palavras simples? Pense no webhook como uma campainha. Em vez de você ir até a porta a cada minuto para ver se chegou alguém, a campainha toca quando há visita. No mundo fiscal, a visita é uma novidade sobre uma nota: ela foi autorizada, rejeitada ou cancelada. Tecnicamente, o webhook é uma chamada HTTP que a API fiscal faz para um endereço informado pela empresa, chamado de URL de destino. Essa chamada leva um conteúdo, geralmente em JSON, com os dados do evento, como o identificador do documento, o novo status e links para baixar o XML e o PDF. ## Para que serve um webhook fiscal? A emissão de documentos como NF-e, NFS-e, NFC-e, CT-e e MDF-e costuma depender de órgãos externos, como a SEFAZ ou a prefeitura. A resposta nem sempre é imediata, por isso muitas plataformas trabalham com fluxo assíncrono: o pedido é aceito na hora, mas o resultado chega depois. O webhook serve para avisar o sistema da empresa sobre esse resultado no momento certo. Assim, o ERP, a loja virtual ou o marketplace pode liberar o pedido, enviar a nota ao cliente, registrar a rejeição para correção ou atualizar a contabilidade sem intervenção manual. ## Como funciona um webhook fiscal na prática? Primeiro, a empresa cadastra na plataforma fiscal uma URL do seu sistema que ficará esperando os avisos e, em muitos casos, escolhe quais eventos quer receber. Depois, ao enviar um documento para emissão, o sistema segue com suas tarefas normalmente. Quando o documento muda de status, a plataforma envia uma requisição para a URL cadastrada. O sistema da empresa lê o conteúdo, confere se o aviso é legítimo, atualiza seus registros e responde com um código de sucesso, como 200. Se não houver resposta ou ocorrer erro, a plataforma normalmente tenta reenviar mais tarde. ## Qual a diferença entre webhook fiscal e polling de status? No polling, o sistema da empresa pergunta à API, de tempos em tempos, qual é a situação de cada documento. Isso gera muitas consultas desnecessárias e pode atrasar a percepção de mudanças, dependendo do intervalo escolhido. No webhook, a lógica se inverte: a plataforma fiscal avisa quando algo acontece. Na prática, muitas integrações usam os dois juntos, com o webhook como canal principal e o polling como verificação de segurança caso algum aviso não seja recebido. ## Como garantir que um webhook fiscal é seguro e confiável? Como a URL de destino fica acessível pela internet, é importante confirmar que o aviso veio mesmo da plataforma fiscal. Uma prática comum é a assinatura com HMAC, em que a plataforma calcula um código a partir do conteúdo e de uma chave secreta, e o sistema da empresa refaz o cálculo para comparar. O uso de HTTPS também é essencial para proteger os dados no caminho. Para confiabilidade, o sistema receptor deve responder rápido e processar o aviso em segundo plano, tratar avisos repetidos sem duplicar ações, aplicando o conceito de idempotência, e registrar tudo em log. Do lado da plataforma, mecanismos de retry com backoff exponencial ajudam a entregar avisos que falharam por instabilidade momentânea. ## Exemplos de Webhook fiscal - Uma loja virtual envia uma NFC-e para emissão e só libera a etiqueta de envio quando recebe o webhook informando que o documento foi autorizado. - Um ERP recebe um webhook de rejeição de NF-e com o motivo informado pela SEFAZ e cria automaticamente uma tarefa para a equipe fiscal corrigir o cadastro do produto. - Uma plataforma de serviços recebe o webhook de NFS-e autorizada contendo o link do PDF e envia a nota por e-mail ao tomador do serviço. - Uma transportadora recebe um webhook confirmando o encerramento de um MDF-e e atualiza o status da viagem em seu sistema de gestão. ## Perguntas frequentes ### Preciso de um servidor próprio para receber webhooks fiscais? Sim, é necessário ter um endereço acessível pela internet, com HTTPS, capaz de receber requisições HTTP. Pode ser parte do backend do seu sistema ou um serviço dedicado apenas a receber e processar esses avisos. ### O que acontece se meu sistema estiver fora do ar quando o webhook for enviado? Em geral, a plataforma tenta reenviar o aviso algumas vezes, com intervalos crescentes. Ainda assim, é recomendável manter uma consulta periódica de status para recuperar eventos que eventualmente não tenham sido entregues. ### Posso receber o mesmo webhook mais de uma vez? Sim. Por causa dos reenvios automáticos, um mesmo evento pode chegar repetido. Por isso, o sistema deve verificar se aquele evento já foi processado antes de executar ações como enviar e-mails ou baixar estoque. ## Termos relacionados - [Polling de status fiscal](https://conota.dev/glossario/polling-de-status-fiscal.md) - [HMAC em webhooks](https://conota.dev/glossario/hmac-em-webhooks.md) - [Fluxo assíncrono de emissão](https://conota.dev/glossario/fluxo-assincrono-de-emissao.md) - [Status de documento fiscal](https://conota.dev/glossario/status-de-documento-fiscal.md) - [Retry na integração fiscal](https://conota.dev/glossario/retry-na-integracao-fiscal.md) - [Idempotência na emissão fiscal](https://conota.dev/glossario/idempotencia-na-emissao-fiscal.md) --- Fonte: [Webhook fiscal](https://conota.dev/glossario/webhook-fiscal/) · Atualizado em 2026-10-22