Como testar o webhook de NFS-e na sua máquina, sem URL pública nem túnel

Testar um webhook costuma exigir uma URL pública: abrir uma porta, subir um túnel, cadastrar o endereço temporário e lembrar de apagar depois. A linha de comando do SDK da Sudrel tira esse passo. Ela lê o log de eventos da sua conta e entrega cada evento no endereço local que você indicar, assinado do mesmo jeito que um webhook de verdade.

Em três passos

• Instale o SDK, que traz a linha de comando: npm install -g @sudrel/sdk.
• Deixe a chave de API no ambiente, de preferência a de sandbox: export SUDREL_API_KEY=sdr_test_....
• Suba o seu recebedor na máquina e aponte a linha de comando para ele.

sudrel eventos seguir --encaminhar http://localhost:3000/webhook

Ao iniciar, ela mostra um segredo local. Use esse segredo no verificador de assinatura do seu recebedor, no lugar do segredo do webhook cadastrado. A partir daí, cada evento novo da conta (nota autorizada, rejeitada, cancelada, lote concluído) chega no seu endereço local, e a linha de comando mostra o status HTTP que o seu recebedor devolveu.

Opções úteis

• Só eventos novos, por padrão. Sem opção nenhuma, ela começa do fim do log e entrega o que acontecer daqui para frente.
• --do-inicio reentrega o log inteiro, para testar o recebedor contra tudo o que já aconteceu.
• --apos <cursor> retoma de um ponto: a linha de comando mostra o cursor depois de cada página entregue.
• --segredo fixa o segredo local, para não trocar a configuração do recebedor a cada execução.
• --intervalo muda de quantos em quantos segundos ela procura evento novo (2 por padrão).

O que testar no seu recebedor

• Assinatura. Recuse o pedido quando a assinatura não confere. Com o segredo local errado, todo evento tem que ser recusado.
• Repetição. A linha de comando tenta de novo até três vezes quando o recebedor não responde 2xx, como o webhook real faz. O seu código precisa deduplicar pelo id do evento.
• Resposta rápida. Responda 2xx logo e processe depois. Recebedor lento é recebedor que recebe o mesmo evento duas vezes.

Os detalhes do formato da assinatura, da tolerância de horário e da retentativa do webhook de produção estão em webhook de NFS-e: assinatura e retentativa.

Perguntas frequentes

Preciso de URL pública para testar o webhook da Sudrel?

Não. A linha de comando do SDK lê os eventos da conta e entrega cada um no endereço local que você indicar, sem abrir porta nem cadastrar webhook.

O evento entregue pela linha de comando é igual ao do webhook?

É assinado do mesmo jeito, com cabeçalhos no mesmo formato, mas com um segredo local que a linha de comando mostra ao iniciar. No verificador, use esse segredo durante o teste.

Funciona com a chave de produção?

Funciona, mas para testar o recebedor a chave de sandbox é melhor: você gera os eventos que quiser emitindo notas de teste, sem custo e sem tocar em nota de verdade.