# Como meu sistema fica sabendo que uma nota foi autorizada ou rejeitada?

Cadastre um webhook no RoboFiscal para receber eventos como nota autorizada, rejeitada ou cancelada. Seu endpoint deve validar a assinatura, registrar a entrega com segurança e responder rapidamente. Processe o trabalho posterior em fila e reconheça reentregas pelo identificador. Mantenha também consultas de conciliação: uma notificação pode atrasar ou exigir nova tentativa.

Revisado em 10 de outubro de 2026 · Equipe RoboFiscal.

## Fatos e fontes

- A RFC 2104 descreve HMAC como mecanismo de autenticação de mensagens com chave compartilhada. [IETF: RFC 2104, autenticação HMAC](https://www.rfc-editor.org/rfc/rfc2104.html).
- A RFC 9110 define o significado das respostas HTTP usadas para confirmar requisições. [IETF: RFC 9110, semântica HTTP](https://www.rfc-editor.org/rfc/rfc9110.html).
- A LGPD prevê proteção contra acesso não autorizado aos dados pessoais tratados. [Planalto: Lei 13.709/2018, arts. 6º e 46](https://www.planalto.gov.br/ccivil_03/_ato2015-2018/2018/lei/l13709.htm).
- A API nacional disponibiliza consultas e eventos para acompanhar documentos fiscais. [Portal NFS-e: manual da API, v1.2](https://www.gov.br/nfse/pt-br/biblioteca/documentacao-tecnica/documentacao-atual/manual-contribuintes-emissor-publico-api-sistema-nacional-nfs-e-v1-2-out2025.pdf).
- O RoboFiscal assina webhooks e mantém um identificador de entrega estável nas retentativas. [RoboFiscal: contrato OpenAPI público](https://robofiscal.com.br/app/api/v1/openapi.yaml).

## Como validar que o evento veio do RoboFiscal?

Leia X-Robofiscal-Timestamp e X-Robofiscal-Signature. Calcule HMAC-SHA256 sobre timestamp, ponto e corpo bruto da requisição, usando o segredo do webhook. Compare a assinatura em tempo constante e aplique uma janela de validade ao timestamp. A serialização do JSON não deve ser refeita antes da verificação, pois isso altera os bytes assinados.

## Como responder sem perder processamento?

Depois de validar, grave duravelmente o identificador e o evento, ou confirme que aquela entrega já foi registrada. Responda 2xx após esse registro e processe as ações seguintes em uma fila. Não espere geração de PDF ou chamadas a outros serviços para responder ao webhook. Se o registro falhar, não confirme uma entrega que será perdida.

## Como tratar eventos repetidos ou fora de ordem?

Use X-Robofiscal-Entrega para reconhecer a mesma entrega. Confira a nota antes de aplicar uma mudança que possa substituir um estado mais recente. Exemplo: uma notificação de autorização recebida com atraso não deve fazer seu sistema esquecer um cancelamento já confirmado. Consulte a API quando houver divergência.

Dados usados na verificação da assinatura, conforme o contrato do RoboFiscal.

```
mensagem = timestamp + "." + corpoBruto
assinaturaEsperada = "sha256=" + HMAC_SHA256(segredo, mensagem)
compararEmTempoConstante(assinaturaRecebida, assinaturaEsperada)
```

## Passo a passo

1. Cadastre uma URL HTTPS e guarde o segredo no servidor.
2. Valide assinatura sobre o corpo bruto e confira o timestamp.
3. Registre a entrega de forma durável e idempotente.
4. Responda rapidamente e processe o trabalho posterior em fila.
5. Monitore falhas e concilie a situação das notas pela API.

## Erros comuns

- Reformatar o JSON antes de verificar a assinatura.
- Responder sucesso antes de guardar o evento ou repetir efeitos a cada retentativa.

## Como o RoboFiscal ajuda

O RoboFiscal oferece eventos de notas e acompanhamento de entregas pela API. O receptor precisa validar a mensagem e controlar seu próprio processamento para evitar perda ou repetição de ações.

Consulte eventos, autenticação e tentativas de entrega antes de cadastrar a integração. [Criar conta grátis](https://robofiscal.com.br/app/registrar).

[Ver eventos e endpoints](https://robofiscal.com.br/app/api/docs).

## Perguntas relacionadas

### O segredo do webhook é a chave de API?

Trate-os como credenciais de finalidades diferentes: a chave autentica chamadas à API e o segredo verifica as notificações.

### Posso usar só webhooks, sem consultas?

Mantenha consultas de conciliação para falhas, atrasos e divergências de estado.

## Continue lendo

- [Como integrar a emissão de NFS-e ao seu sistema por API?](https://robofiscal.com.br/api-nfs-e.html)
- [Como evitar NFS-e duplicada ao reenviar uma requisição?](https://robofiscal.com.br/docs/evitar-nfse-duplicada/)
- [O que fazer quando a emissão de NFS-e fica indisponível?](https://robofiscal.com.br/docs/nfse-indisponivel-timeout/)

Página: https://robofiscal.com.br/docs/webhooks-nfse/