Webhooks de Notas de Saída (DF-e)
Cadastrar endpoints, filtrar eventos de emissão e receber notificações em tempo real de NF-e, NFC-e, NFS-e, CT-e e MDF-e.
Os Webhooks de Notas de Saída (DF-e) permitem que o seu ERP, e-commerce ou sistema de faturamento receba notificações assíncronas instantâneas sobre todas as emissões fiscais realizadas pela sua empresa: NF-e (Produto), NFC-e (Varejo), NFS-e (Serviços), CT-e (Transporte) e MDF-e (Manifesto).
Você pode cadastrar e gerenciar seus endpoints diretamente pelo Dashboard da NFER ou programaticamente via API REST. Cada endpoint é vinculado à sua empresa e recebe uma chave secreta exclusiva (whsec_...) para validação de assinaturas HMAC-SHA256.
1. Endpoints de Gerenciamento da API
| Operação | Método e Rota | Referência Técnica |
|---|---|---|
| Cadastrar Endpoint de Webhook | POST /v1/webhooks | Ver Parâmetros → |
| Listar Webhooks Cadastrados | GET /v1/webhooks | Ver Listagem → |
| Atualizar URL ou Eventos | PUT /v1/webhooks/:id | Ver Atualização → |
| Remover Endpoint de Webhook | DELETE /v1/webhooks/:id | Ver Exclusão → |
| Rotacionar Secret HMAC | POST /v1/webhooks/:id/rotate-secret | Ver Rotação de Secret → |
| Testar Conectividade HTTP | POST /v1/webhooks/:id/test-connection | Ver Ping de Teste → |
| Disparar Evento Simulado | POST /v1/webhooks/:id/test | Ver Disparo Fake → |
| Histórico de Entregas & Logs | GET /v1/webhooks/:id/deliveries | Ver Entregas → |
2. Eventos Suportados de Notas de Saída
Você pode cadastrar endpoints específicos para determinados eventos de emissão ou utilizar "*" para assinar todas as notas de saída:
| Evento | Documento | Descrição do Disparo |
|---|---|---|
nfe.autorizada | NF-e / NFC-e | Documento autorizado com sucesso na SEFAZ (cStat 100/150). Retorna chave de 44 dígitos e protocolo. |
nfe.erro | NF-e / NFC-e | Emissão rejeitada pelo Fisco. Retorna erroCstat e erroMotivo com a justificativa técnica. |
nfe.cancelada | NF-e / NFC-e | Cancelamento fiscal (evento 110111) homologado com sucesso na SEFAZ. |
nfe.denegada | NF-e / NFC-e | Uso denegado pela SEFAZ por irregularidade cadastral do emitente ou destinatário. |
nfe.contingencia | NF-e / NFC-e | Nota gerada em contingência offline (NFC-e) ou em SVC (SEFAZ Virtual de Contingência). |
nfe.batch.completed | NF-e (Lote) | Processamento assíncrono de lote concluído com sucesso. |
nfse.autorizada | NFS-e Nacional | Nota fiscal de serviço autorizada perante o ADN / prefeitura com link do XML e PDF. |
cte.autorizado | CT-e | Conhecimento de Transporte emitido e autorizado perante a SEFAZ. |
mdfe.autorizado | MDF-e | Manifesto Eletrônico de Documentos Fiscais autorizado com DAMDFE. |
Para ver os schemas completos e exemplos de payloads JSON de cada evento, acesse o Catálogo de Eventos de Emissão.
3. Cadastrando um Endpoint para Notas de Saída via cURL
Para criar um novo endpoint inscrito nos eventos de notas de saída, informe a URL pública HTTPS e a lista de eventos desejados:
Resposta de sucesso retornando o identificador e a chave secreta gerada:
4. Rotação de Segredo sem Downtime
Se houver suspeita de vazamento de credenciais ou para cumprir políticas corporativas periódicas de segurança, utilize o endpoint de rotação:
A NFER mantém um período de carência (dual-signature) de 24 horas onde você pode validar tanto com a chave anterior quanto com a nova, permitindo atualizar o deploy dos seus servidores sem descartar entregas legítimas.