Skip to main content

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:
  1. Acesse Configurações > Webhooks
  2. Adicione a URL do seu endpoint
  3. Selecione os eventos que deseja receber
  4. 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 HookDebugPara 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