1 - Visão geral e conceito

O recurso de Webhooks faz o TryERP avisar um sistema do cliente assim que um documento fiscal muda de situação: quando a NF-e é autorizada, quando é cancelada, quando o MDF-e é encerrado. O aviso é uma chamada HTTP para um endereço que o próprio cliente cadastra.

Em uma frase: em vez de o sistema do cliente ficar perguntando "já autorizou?", o TryERP avisa quando autoriza.

1. Por que isso existe

Quem usa este recurso normalmente já contratou a API do TryERP e consegue ler os dados da nota por lá. O problema nunca foi o acesso ao dado — era saber a hora certa de buscar.

Sem webhook, a única saída é o sistema do cliente consultar a API de tempos em tempos (polling). Isso tem três defeitos conhecidos:

O webhook não substitui a API — ele a complementa. A notificação carrega a chave de acesso, o protocolo e os dados de identificação do documento. Se o sistema do cliente precisar do XML, dos itens ou dos impostos, ele continua buscando na API, só que na hora certa, uma vez, em vez de ficar perguntando.

2. O que dispara uma notificação

O cancelamento de CT-e OS não dispara porque o próprio sistema ainda não implementa esse evento. O encerramento só existe no MDF-e.

Só há notificação quando a SEFAZ confirma o evento. Rejeição não notifica, lote em processamento não notifica, erro de comunicação não notifica. O webhook avisa fato consumado — nunca tentativa.

3. A garantia de entrega, e por que ela foi feita assim

Um endpoint do cliente pode estar fora do ar exatamente no minuto em que a nota é autorizada. Se a notificação fosse "tenta uma vez e esquece", o cliente perderia o aviso e nunca saberia disso. O desenho evita esse buraco em três camadas:

O efeito prático da camada 1 é o que importa: se a nota foi autorizada, a notificação existe. Ela pode demorar, pode precisar de várias tentativas, pode ser reenviada manualmente — mas não some. Não existe o caso "a nota autorizou e ninguém nunca soube".

4. O que o recurso deliberadamente não faz

• Não envia o XML nem o DANFE. A notificação é um aviso enxuto com a chave e o protocolo; o arquivo vem da API. Mandar XML por webhook engordaria cada chamada e obrigaria a repetir tudo a cada tentativa de reenvio.
• Não tenta para sempre. Há um limite de tentativas por endpoint (padrão 5). Depois disso a notificação fica marcada como Descartado e espera reenvio manual — o sistema não fica batendo indefinidamente em um endereço que não responde.
• Não garante ordem. Se duas notas são autorizadas no mesmo segundo, não há promessa de que cheguem na ordem de emissão.
• Não avisa rejeição. Ver o callout da seção 2.

5. Quem não usa não paga nada por isso

Esta é uma decisão de projeto que vale registrar, porque protege a empresa inteira: enquanto não houver nenhum endpoint cadastrado e ativo, o recurso não custa nada no fluxo de emissão.

O sistema mantém em memória a lista de quais filiais têm webhook ativo e a atualiza no máximo uma vez por minuto. Na emissão, a verificação é uma consulta a essa lista em memória — não há consulta ao banco por nota emitida, nem processo de envio iniciado. Para quem nunca vai usar o recurso, a emissão continua exatamente como era.

6. O ciclo completo, e quem faz cada parte

Próximo capítulo: Configuração inicial — o que precisa estar em ordem antes de cadastrar o primeiro endpoint.