Configuração de Webhooks
Os webhooks da ValidaNFe permitem que sua aplicação receba notificações automáticas quando eventos importantes acontecem, como conclusão de consultas, mudanças de status ou erros.
Como Funcionam
Quando um evento ocorre, a ValidaNFe envia uma requisição HTTP POST para a URL configurada em sua conta, contendo os dados do evento em formato JSON.
Os webhooks são enviados de forma assíncrona e incluem tentativas de reenvio automáticas em caso de falha.
Eventos Disponíveis
Disparado quando uma consulta de NFe é processada com sucesso. {
"evento" : "nfe.consulta.concluida" ,
"timestamp" : "2024-01-15T10:30:00Z" ,
"dados" : {
"chave_nfe" : "35170608530528000184550000000154301000771561" ,
"status" : "autorizada" ,
"tipo_consulta" : "completa"
}
}
Disparado quando ocorre um erro durante a consulta. {
"evento" : "nfe.consulta.erro" ,
"timestamp" : "2024-01-15T10:30:00Z" ,
"dados" : {
"chave_nfe" : "35170608530528000184550000000154301000771561" ,
"erro_codigo" : "404" ,
"erro_mensagem" : "NFe não encontrada"
}
}
Disparado quando uma NFe é armazenada com sucesso no GuardaNFe. {
"evento" : "guarda.upload.concluido" ,
"timestamp" : "2024-01-15T10:30:00Z" ,
"dados" : {
"chave_nfe" : "35170608530528000184550000000154301000771561" ,
"arquivo_id" : "abc123def456" ,
"url_download" : "https://api.validanfe.com/guarda/download/abc123def456"
}
}
Configuração
1. Configurar URL do Webhook
No painel administrativo da ValidaNFe:
Acesse Configurações > Webhooks
Adicione a URL do seu endpoint
Selecione os eventos que deseja receber
Configure o secret para validação (recomendado)
2. Implementar o Endpoint
const express = require ( 'express' );
const crypto = require ( 'crypto' );
const app = express ();
app . use ( express . json ());
app . post ( '/webhook/validanfe' , ( req , res ) => {
// Validar assinatura
const signature = req . headers [ 'x-validanfe-signature' ];
const payload = JSON . stringify ( req . body );
const expectedSignature = crypto
. createHmac ( 'sha256' , process . env . WEBHOOK_SECRET )
. update ( payload )
. digest ( 'hex' );
if ( signature !== `sha256= ${ expectedSignature } ` ) {
return res . status ( 401 ). send ( 'Assinatura inválida' );
}
// Processar evento
const { evento , dados } = req . body ;
switch ( evento ) {
case 'nfe.consulta.concluida' :
console . log ( 'NFe consultada:' , dados . chave_nfe );
// Sua lógica aqui
break ;
case 'nfe.consulta.erro' :
console . log ( 'Erro na consulta:' , dados . erro_mensagem );
// Sua lógica de tratamento de erro
break ;
}
res . status ( 200 ). send ( 'OK' );
});
Segurança
Validação de Assinatura
Sempre valide a assinatura do webhook usando o secret configurado:
const crypto = require ( 'crypto' );
const validarAssinatura = ( payload , signature , secret ) => {
const expectedSignature = crypto
. createHmac ( 'sha256' , secret )
. update ( payload )
. digest ( 'hex' );
return signature === `sha256= ${ expectedSignature } ` ;
};
Boas Práticas
Use HTTPS : Configure URLs apenas com HTTPS
Valide sempre : Nunca processe webhooks sem validar a assinatura
Responda rapidamente : Retorne status 200 em até 30 segundos
Seja idempotente : Prepare-se para receber o mesmo evento múltiplas vezes
Retry e Timeout
Timeout : 30 segundos por tentativa
Retry : Até 3 tentativas com backoff exponencial
Intervalos : 1min, 5min, 30min
Se seu endpoint continuar falhando, os webhooks podem ser desabilitados automaticamente. Configure monitoramento adequado.
Testando Webhooks
Use ferramentas como ngrok para testar localmente:
# Expor porta local
ngrok http 3000
# Configure a URL no painel: https://abc123.ngrok.io/webhook/validanfe
Teste Rapidamente com HookDebug Para testar e visualizar requisições de webhook de forma rápida, use o HookDebug . Você receberá uma URL temporária que mostra todas as requisições recebidas em tempo real, incluindo headers, payload e detalhes da requisição.
Monitoramento
Monitore seus webhooks através do painel administrativo:
Logs de entrega : Histórico de todos os webhooks enviados
Taxa de sucesso : Percentual de entregas bem-sucedidas
Tentativas : Detalhes sobre tentativas e falhas
Precisa de Ajuda? Entre em contato para suporte na configuração de webhooks