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.