Webhooks

O webhook é a forma principal de a sua aplicação receber as notas. Com o monitoramento ativo, a cada documento capturado a Nota Gateway faz um POST para a URL que você cadastrou, já com o mesmo JSON da nota que as rotas de documento retornam. Você não precisa ficar consultando: a nota chega até você.

A consulta continua existindo, mas como via de reconciliação e auditoria — para conferir o histórico ou reprocessar um intervalo —, não como forma principal de descoberta.

Cadastro

O webhook é registrado pelo painel, não pela API. Em Web hooks, clique em Novo web hook e preencha:

Campo	Obrigatório	O que é
URL	Sim	O endpoint HTTPS da sua aplicação que vai receber o POST.
Content-Type	Sim	Formato do corpo enviado. Padrão application/json.
Token	Não	Um valor secreto que enviamos junto da requisição, para o seu endpoint confirmar que a chamada veio da Nota Gateway.

Você pode cadastrar mais de um webhook, e cada um tem um estado Ativado que liga ou desliga a entrega sem precisar apagar o registro.

Payload

O payload enviado é o mesmo JSON da nota retornado pelas rotas de documento. O cabeçalho em que o Token viaja, a política de retentativa quando o seu endpoint não responde 2xx e a assinatura da requisição são detalhados na documentação do webhook.

O que o seu endpoint deve fazer

• Responder rápido com 2xx. Confirme o recebimento antes de processar; faça o trabalho pesado de forma assíncrona.
• Ser idempotente. Trate cada nota pela chave de acesso: se a mesma nota chegar duas vezes, o resultado deve ser o mesmo.
• Validar a origem. Se você cadastrou um Token, confira-o antes de aceitar a requisição.

Quando ainda usar consulta

O webhook cobre o caminho feliz. A consulta é a rede de segurança para os casos em que ele não basta:

• Seu endpoint ficou fora do ar e você quer reprocessar um intervalo.
• Você precisa reconciliar e provar que nenhuma nota ficou de fora.
• Você está integrando pela primeira vez e quer ler o histórico já capturado.