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:

Problema do polling	Consequência prática
Consulta que quase sempre volta vazia	Gasto de processamento e banda dos dois lados para não descobrir nada
Intervalo grande	O sistema do cliente demora a reagir — o pedido fica parado esperando a nota que já existe
Intervalo pequeno	Carga desnecessária no servidor, que cresce com o número de clientes integrados

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

Documento	Autorização	Cancelamento	Encerramento
NF-e (modelo 55)	Sim	Sim	—
NFC-e (modelo 65)	Sim	Sim	—
CT-e	Sim	Sim	—
CT-e OS	Sim	—	—
MDF-e	Sim	Sim	Sim

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:

#	Camada	O que faz
1	Registro junto com o documento	No instante em que o sistema grava "nota autorizada", ele grava também a notificação pendente — na mesma transação. Ou as duas coisas existem, ou nenhuma existe
2	Envio imediato	Logo depois, a notificação é enviada em segundo plano. É o caminho normal: o cliente recebe em segundos
3	Rede de segurança	Uma rotina roda a cada 2 minutos e reenvia tudo que não conseguiu sair — endpoint fora do ar, sistema fechado antes do envio terminar, queda de rede

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

#	Passo	Quem faz	Onde
1	Construir o endereço que vai receber as notificações	Desenvolvedor do cliente	Capítulo Guia para o desenvolvedor do endpoint
2	Liberar o acesso à tela e conferir a rede	Administrador	Capítulo Configuração inicial
3	Cadastrar o endpoint e testar	Responsável pela integração	Capítulo Cadastrar um endpoint
4	Combinar com o cliente o que será enviado	Responsável pela integração	Capítulo Eventos e o conteúdo enviado
5	Acompanhar entregas e reenviar o que falhou	Responsável pela integração / suporte	Capítulo Entrega, reenvio e histórico

---

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