Webhooks¶

Em uma frase. Cadastro dos endereços do seu sistema que recebem um aviso automático quando uma NF-e é autorizada, rejeitada, denegada, cancelada ou recebe um evento — e o log de cada aviso enviado, com resposta, tentativas e reenvio.

Quem usa: equipe de integração do ERP, suporte · Frequência: na implantação da integração e ao investigar um aviso que não chegou · Pré-requisitos: um endereço HTTPS no seu sistema pronto para receber POST com corpo JSON

Para que serve¶

Sem webhook, o ERP precisa perguntar à API de tempos em tempos se a nota já foi autorizada. Com webhook, o app avisa: assim que a SEFAZ responde, ele faz um POST no endereço cadastrado com os dados da nota e os links para baixar XML e DANFE.

Cada endereço cadastrado é um endpoint. Cada aviso enviado a um endpoint é uma entrega. A tela tem as duas visões: a lista de endpoints e o log de entregas.

Como chegar¶

No Hub, abra o app Invent Docs Flow NF-e.
Selecione o tile Webhooks.

A tela de listagem¶

O subtítulo informa quantos endpoints existem, de um máximo de 10 por tenant ("N de 10 endpoints"). Com o limite atingido, Novo endpoint fica desligado.

Coluna	Conteúdo
URL / Descrição	Endereço e, abaixo, a descrição
Eventos	"todos" quando assina tudo; senão "N evento(s)" — passe o mouse para ver a lista
Escopo	Todas as empresas ou Empresa específica
Saúde	Selo de situação (ver abaixo)
Última entrega	Data e hora da entrega mais recente dos últimos 7 dias; ícone de alerta quando ela não foi entregue. Ordenável
Taxa 7d	Percentual de entregas com status Entregue nos últimos 7 dias: verde a partir de 99 %, amarelo a partir de 90 %, vermelho abaixo
Ações	Editar · Ver entregas deste endpoint · Enviar evento de teste · Reativar (só em endpoint inativo) · Excluir

Saúde do endpoint¶

Selo	Significado
Ativo	Recebendo normalmente
Falhando	Ativo, mas a última tentativa de entrega falhou
Desativado (auto)	Ficou 72 horas seguidas sem nenhuma resposta de sucesso e foi desligado pelo sistema
Inativo	Desligado manualmente (pela API; a tela não tem chave de ativar/desativar)

Com endpoint desativado automaticamente, a tela mostra o alerta "1 endpoint foi desativado automaticamente após falhas contínuas. Corrija o receptor e use "Reativar"."

Ações da listagem¶

Ação	O que faz
Ver entregas	Abre o log de entregas de todos os endpoints
Novo endpoint	Abre o formulário em branco
Ícone de teste	Envia um evento de teste (`ping`). Desligado em endpoint inativo
Reativar endpoint	Liga de novo e zera o contador de falhas: "Endpoint reativado — contadores de falha zerados."
Lixeira	Confirma e remove: "As entregas pendentes serão canceladas; o histórico de entregas é preservado."

Cadastro e edição¶

Destino¶

Campo	Obrigatório	Formato / domínio	Regra	Registro / campo fiscal
URL	sim	Endereço `https://…`, até 2048 caracteres	HTTPS obrigatório; não pode ter usuário e senha na URL; o endereço precisa existir e não pode apontar para rede interna	—
Descrição	não	Texto, até 140 caracteres na tela	Rótulo livre, ex.: "ERP produção"	—

A dica do campo lembra que cada POST leva os headers webhook-id, webhook-timestamp e webhook-signature (HMAC-SHA256).

Eventos assinados¶

Pelo menos um é obrigatório. Os tipos aparecem em grupos:

Grupo	Tipo	Quando dispara	Relação fiscal
Nota Fiscal	`nfe.autorizada`	NF-e/NFC-e autorizada	Protocolo de autorização
Nota Fiscal	`nfe.rejeitada`	NF-e rejeitada pela SEFAZ	cStat de rejeição
Nota Fiscal	`nfe.denegada`	NF-e denegada	Documento denegado
Eventos fiscais	`nfe.cancelada`	Cancelamento registrado	Evento 110111
Eventos fiscais	`nfe.carta_correcao`	Carta de Correção registrada	Evento 110110
Eventos fiscais	`nfe.evento`	Demais eventos do emitente (IBS/CBS/IS)	Eventos da NT 2025.002
Recepção	`nfe.manifestacao`	Manifestação do destinatário, inclusive a ciência automática da captura	Eventos de manifestação (ex.: 210200)
Recepção	`dfe.recebido`	Documento de terceiro capturado ou recebido	—

O teste (ping) nunca é assinado: só é enviado pelo botão de teste.

Anexos no payload¶

Opção	O que vai no aviso
Somente links (recomendado)	Links da API para XML e DANFE
Incluir XML	O XML em base64 dentro do aviso
Incluir XML + PDF	XML e PDF (DANFE, DANFE com tarja no cancelamento ou DACCe na carta de correção) em base64

Nota rejeitada ou denegada vai sem anexo, porque não há XML autorizado. Se o aviso com anexos passar de 8 MB, ele sai sem os anexos, com os links, e o campo data.arquivos marca omitidos.

Escopo¶

Todas as empresas do tenant ou Empresa específica (escolhida numa lista). No escopo por empresa, o endpoint só recebe avisos daquela empresa.

Secret de assinatura¶

Ao criar o endpoint, abre-se a janela "Endpoint criado — copie o secret agora". O secret (whsec_…) assina todos os avisos daquele endpoint e não é exibido novamente. O botão Concluir só libera depois de marcar "Salvei o secret em local seguro".

Na edição, a seção Secret de assinatura mostra só o começo do secret (whsec_abc123••••••••), a data de criação e dois botões:

Rotacionar secret — gera um novo secret e o exibe uma única vez. "O secret atual continua válido por 24h (dupla assinatura no header) e depois expira."
Enviar evento de teste — igual ao botão da listagem.

Sub-telas¶

Entregas de webhooks¶

Aberta por Ver entregas (todos os endpoints) ou pelo ícone da linha (já filtrada naquele endpoint). Subtítulo: "Entregas são retidas por 30 dias."

Cards clicáveis, que filtram a lista:

Card	Conta
Pendentes	Pendente + Retentando
Entregues	Entregue
Falhas	Falha
Canceladas	Cancelada

Filtros: endpoint, período De / Até (abre no dia de hoje) e Mais filtros — Situação (várias), Tipo de evento (inclui "Teste (ping)") e Chave de acesso (busca exata, 44 dígitos).

Coluna	Conteúdo
Quando	Criação da entrega. Ordenável; padrão mais recente primeiro
Chave	Chave de acesso, com botão de copiar
Status	Selo; em Retentando, mostra "próxima: data e hora"
Evento	Tipo do evento. Ordenável
Endpoint	URL, ou "(endpoint removido)"
HTTP	Código da última resposta. Ordenável
Tent.	Tentativas feitas
Ações	Ver detalhes · Reenviar (em Falha, Cancelada ou Entregue)

Status da entrega

Status	Significado
Pendente	Na fila para envio ou para nova tentativa em poucos minutos
Retentando	Aguardando uma tentativa agendada para mais tarde
Entregue	O endpoint respondeu com sucesso (2xx)
Falha	Tentativas esgotadas ou resposta que não admite nova tentativa
Cancelada	O endpoint foi desativado ou removido antes de a entrega sair

Detalhe da entrega¶

Mostra o webhook-id, o endpoint, o Payload enviado (o JSON), a Última resposta (HTTP, duração e trecho do erro) e a tabela Tentativas (número, quando, HTTP, duração, erro). O botão Reenviar agora reenvia a mesma entrega: "Entrega re-enfileirada (mesmo webhook-id e corpo)."

Regras de negócio¶

RN-WHK-001 — Até 10 endpoints por tenant.
RN-WHK-002 — HTTPS e endereço público. URL sem HTTPS, sem host, com credenciais, que não resolve ou que aponta para rede interna é recusada ao salvar.
RN-WHK-003 — Ao menos um evento. O curinga "todos" assina todos os tipos, exceto o teste.
RN-WHK-004 — Um aviso por ocorrência. A mesma ocorrência (por exemplo, a autorização de uma chave) gera uma única entrega por endpoint, mesmo que o processamento se repita. Cada teste gera uma entrega nova.
RN-WHK-005 — O webhook-id não muda. Novas tentativas e reenvios usam o mesmo webhook-id e o mesmo corpo: o seu sistema deve ignorar um id já processado.
RN-WHK-006 — Responder 2xx em até 10 segundos. Qualquer outra resposta, ou o tempo esgotado, conta como falha.
RN-WHK-007 — Novas tentativas automáticas. Sem resposta, erro 5xx, 408, 425 ou 429 geram nova tentativa após 30 s, 2 min, 10 min, 1 h, 4 h, 12 h, 24 h, 24 h e 24 h — até 10 tentativas. Um Retry-After na resposta substitui o intervalo. Demais respostas (3xx e 4xx) encerram a entrega em Falha na hora.
RN-WHK-008 — Desativação automática. Endpoint sem nenhuma resposta de sucesso por 72 horas seguidas é desativado, e suas entregas pendentes são canceladas.
RN-WHK-009 — Reenviar e testar exigem endpoint ativo. "Reative o endpoint para reenviar esta entrega." / "Reative o endpoint para enviar um teste."
RN-WHK-010 — Secret exibido uma vez. Perdido o secret, rotacione. Após a rotação, os dois secrets assinam cada aviso por 24 horas.
RN-WHK-011 — Remover preserva o histórico. As entregas pendentes são canceladas e o log continua consultável, com "(endpoint removido)".
RN-WHK-012 — Log retido por 30 dias. Entregas mais antigas são apagadas automaticamente.
RN-WHK-013 — Aviso nunca atrasa a nota. Uma falha do webhook não afeta a autorização nem o evento, que já foram confirmados pela SEFAZ.

O que esta tela não faz¶

Não garante entrega única. O mesmo aviso pode chegar mais de uma vez; deduplique pelo webhook-id.
Não reexibe o secret. Só rotaciona.
Não guarda o conteúdo dos anexos. O XML e o PDF são montados na hora de cada tentativa.
Não envia e-mail. O envio de XML e DANFE por e-mail é configurado em Configurações ▸ Emissão.
Não substitui a consulta pela API. Os links do aviso apontam para a API, que exige o mesmo token de acesso da integração.

Erros e mensagens¶

Mensagem	Causa	O que fazer
Informe a URL do endpoint.	URL vazia	Preencher
Selecione ao menos um tipo de evento.	Nenhum evento marcado	Marcar pelo menos um
Selecione a empresa do escopo.	Escopo por empresa sem empresa	Escolher a empresa
URL de webhook deve usar HTTPS.	Endereço `http://`	Usar HTTPS
URL de webhook sem host. / URL de webhook inválida: …	URL mal formada	Corrigir
URL de webhook não pode conter credenciais (user@).	Usuário/senha na URL	Retirar e autenticar pelo secret
Host do webhook não pôde ser resolvido: …	Domínio inexistente	Conferir o endereço
URL de webhook resolve para endereço privado/reservado (…)	Endereço de rede interna	Usar um endereço público
Limite de 10 endpoints de webhook por tenant atingido.	Limite	Remover um endpoint
Reative o endpoint para reenviar esta entrega.	Reenvio com endpoint inativo	Reativar antes
O endpoint desta entrega foi removido.	Reenvio de entrega de endpoint excluído	Cadastrar o endpoint de novo
Falha ao salvar o endpoint. / Falha ao enviar o teste. / Falha ao reenviar.	Erro na operação	Tentar de novo; persistindo, acionar o suporte

Hoje a tela mostra só a mensagem genérica. As mensagens do servidor listadas acima (URL, limite, endpoint inativo) são as que a API devolve, mas a tela ainda exibe apenas "Falha ao salvar o endpoint.", "Falha ao enviar o teste." ou "Falha ao reenviar.". Diante de uma delas, confira os pontos da tabela.

Relação com a NF-e / SEFAZ / EFD¶

O webhook avisa sobre o que já aconteceu na SEFAZ; ele não altera a nota nem a escrituração.

Tipo	Origem na NF-e
`nfe.autorizada` / `nfe.rejeitada` / `nfe.denegada`	Retorno da autorização (cStat e protocolo)
`nfe.cancelada`	Evento 110111 homologado
`nfe.carta_correcao`	Evento 110110 homologado
`nfe.evento`	Eventos IBS/CBS/IS da NT 2025.002; o código específico vem em `data.evento.codigo`
`nfe.manifestacao`	Manifestação do destinatário (NT 2020.001)
`dfe.recebido`	Documento de terceiro obtido pela captura ou pelo upload

Para a EFD, o que conta é a nota e seus eventos no app — não o aviso.

Perguntas frequentes¶

Como meu sistema confere que o aviso veio do app? Recalcule o HMAC-SHA256 de {webhook-id}.{webhook-timestamp}.{corpo} com o secret e compare com o webhook-signature. O procedimento completo está no guia de integração de webhooks.

O aviso chegou duas vezes. Pode acontecer após uma nova tentativa. Use o webhook-id para ignorar a repetição.

Corrigi meu receptor. As entregas que falharam voltam sozinhas? Não. Reative o endpoint, se ele estiver desativado, e use Reenviar em cada entrega.

A Taxa 7d mostra "—". Não houve entrega para esse endpoint nos últimos 7 dias.