Webhooks

Receba avisos automáticos no seu sistema quando uma nota é autorizada, rejeitada ou cancelada, quando chega uma nota recebida e mais.

Para: Escritório, Integrador (API) · Atualizado em 13/10/2026

Para que serve

Um webhook é um aviso que o emissor manda, pela internet, para um endereço do seu sistema (ERP, automação) quando algo acontece — por exemplo, quando uma NFS-e é autorizada. Assim o seu sistema fica sabendo na hora, sem precisar perguntar à API de tempos em tempos.

Na tela Webhooks (menu Configurações → Webhooks) você cadastra os endereços e escolhe os eventos.

Quem vê (lista e histórico de entregas): quem tem a permissão de ver webhooks (Dono, Administrador e Integrador). Quem cria, edita, testa, reenvia e remove: quem pode alterar webhooks (Dono e Administrador).

Passo a passo

Criar um webhook

Clique em + Novo.
Preencha o Nome (ex.: "ERP Produção").
Em Cliente, escolha Todos os clientes ou um cliente específico. Se o seu acesso é restrito a alguns clientes (restrição por cliente), escolher o cliente é obrigatório.
Em URL, informe o endereço que vai receber os avisos. Ele precisa começar com https:// e ser público na internet.
Em Eventos, marque o que quer receber. Vêm marcados "NFS-e autorizada" e "NFS-e cancelada".
Clique em Criar.
No alto da tela aparece Segredo gerado (visível apenas agora). Copie e guarde: ele serve para o seu sistema conferir a assinatura do webhook de cada aviso. O segredo não aparece de novo.

Conferir a lista

A tabela mostra Nome, Cliente, URL, Eventos, Ativo ("sim" ou "pausado") e as Ações.

Testar

Clique em Testar na linha do webhook. O sistema manda um aviso de teste (evento webhook.test), assinado como os demais, e mostra "Envio de teste enfileirado". O resultado aparece no Histórico em alguns segundos.

Ver o histórico de entregas e reenviar

Clique em Histórico na linha do webhook. Aparecem as até 200 entregas mais recentes: quando foi criada, o evento, a situação (Pendente, Entregue, Falhou — vai tentar de novo — ou Falha definitiva), o código HTTP que o seu sistema respondeu, o número de tentativas e o começo da resposta.
Numa entrega que falhou, clique em Reenviar: ela volta para a fila e é tentada de novo do zero.
Use Atualizar para ver a situação mais recente e Fechar para esconder o quadro.

Editar ou pausar

Clique em Editar.
Altere o Nome, a URL e os Eventos. Para parar de receber avisos sem apagar o webhook, desmarque Ativo.
Clique em Salvar. O segredo continua o mesmo. O cliente do webhook não muda na edição: para outro cliente, crie um webhook novo.

Remover

Clique em Remover e confirme. Os avisos param na hora e o histórico de entregas do webhook é apagado.

Campos

Campo	O que significa
Nome	Identificação do webhook.
Cliente	De qual cliente emitente vêm os avisos. "Todos os clientes" inclui os que forem cadastrados depois.
URL	Endereço `https://` público do seu sistema. Endereços internos (localhost, rede privada), com usuário e senha embutidos ou com redirecionamento não são aceitos.
Eventos	Os acontecimentos que geram aviso (tabela abaixo).
Segredo	Chave mostrada uma única vez, usada para assinar os avisos.

Eventos

Evento	Código	Quando
NFS-e autorizada	`nfse.authorized`	A Sefin Nacional autorizou a nota.
DPS rejeitada	`nfse.rejected`	A DPS foi rejeitada (com o código da rejeição).
NFS-e cancelada	`nfse.cancelled`	O cancelamento foi aceito.
NFS-e substituída	`nfse.replaced`	A nota foi substituída por outra.
Falha ao registrar evento	`nfse.event.failed`	Um evento da nota (ex.: cancelamento) foi recusado.
Nota recebida (DF-e)	`dfe.received`	Chegou uma nota em que o cliente é tomador (DF-e).
NF-e recebida	`nfe.received`	Chegou uma NF-e nova em que o cliente é destinatário.
NF-e recebida cancelada pelo emitente	`nfe.cancelled`	O emitente cancelou uma NF-e recebida pelo cliente.
Manifestação de NF-e registrada	`nfe.manifestation.registered`	A SEFAZ registrou uma manifestação do destinatário.
Manifestação de NF-e rejeitada	`nfe.manifestation.rejected`	A SEFAZ recusou uma manifestação (o motivo vem no aviso).
Certificado vencendo	`cert.expiring`	O certificado digital A1 está perto de vencer (30, 15, 7 e 1 dia).
Certificado vencido	`cert.expired`	O certificado venceu.
Cobrança gerada	`cobranca.gerada`	Uma cobrança foi gerada para o tomador.
Cobrança paga	`cobranca.paga`	O pagamento foi confirmado.
Cobrança vencida	`cobranca.vencida`	A cobrança venceu sem pagamento.
Cobrança cancelada	`cobranca.cancelada`	A cobrança foi cancelada (inclusive junto com a nota).
Cobrança estornada	`cobranca.estornada`	O pagamento foi estornado ou contestado.
Pedido de nota criado (portal)	`pedido.criado`	O cliente pediu uma nota pelo portal.
Pedido de nota atualizado	`pedido.atualizado`	O pedido mudou de situação (assumido, emitido, recusado ou cancelado).

Como o aviso chega ao seu sistema

Para quem vai programar o recebimento (detalhes e exemplos na documentação da API):

O aviso é um POST com um corpo JSON. Cada aviso tem um identificador único (id): use-o para ignorar repetições, porque o mesmo aviso pode chegar mais de uma vez.
Os cabeçalhos trazem o webhook (x-webhook-id, o mesmo em todos os avisos dele), o evento (x-webhook-event), a hora (x-webhook-timestamp) e a assinatura (x-webhook-signature). Confira a assinatura com o segredo e recuse avisos com mais de 5 minutos.
O seu sistema deve responder com sucesso (código 2xx) em até 10 segundos. Redirecionamentos contam como falha.
Se falhar, o emissor faz até 6 tentativas no total: a primeira na hora e as outras depois de 1 minuto, 5 minutos, 30 minutos, 2 horas e 12 horas. Depois disso a entrega fica como falha definitiva e pode ser reenviada em Histórico › Reenviar (ou pela API).
Para trocar o segredo, crie um webhook novo e remova o antigo (o sistema não troca o segredo sozinho).

Erros comuns e como resolver

Mensagem ou situação	O que fazer
URL recusada	Use um endereço `https://` público, sem usuário e senha e sem apontar para a rede interna. Veja URL recusada.
"Escolha o cliente do webhook: seu acesso é restrito a alguns clientes."	Selecione um dos seus clientes em Cliente. Veja Informe o cliente.
O botão Criar está desabilitado	Marque ao menos um evento (e escolha o cliente, se for obrigatório).
Não copiei o segredo	Ele não aparece de novo. Crie outro webhook e remova o antigo (Remover).
Meu sistema não recebe os avisos	Clique em Testar e veja o Histórico: o código HTTP e o começo da resposta mostram o problema. Confira se o endereço está acessível pela internet, responde em menos de 10 segundos e não redireciona.
"Entrega não está em estado falho — nada para retomar"	Só entregas que falharam podem ser reenviadas. Clique em Atualizar.
Não aparece o botão + Novo	Você pode ver os webhooks, mas não criar. Peça ao Dono ou a um Administrador.

Veja também

Use Carregar mais para continuar a listagem (50 registros por página) até o fim. Em caso de falha, tente novamente; os registros já carregados são mantidos.

Termos usados

Webhook: Aviso automático que o sistema envia para um endereço seu quando algo acontece (ex.: nota autorizada).
NFS-e: Nota Fiscal de Serviço eletrônica: o documento fiscal que comprova a prestação de um serviço.
Restrição por cliente: Limita o acesso de uma pessoa, contador ou token de API a alguns clientes da conta, em vez de todos.
Assinatura do webhook (HMAC): Código calculado com o segredo do webhook que prova que o aviso veio mesmo do emissor.
DPS: Declaração de Prestação de Serviço: os dados da nota que o sistema assina e envia para virar NFS-e.
DF-e: Documentos fiscais eletrônicos distribuídos pelo ADN — aqui, as notas em que o cliente é tomador.
Certificado digital A1: Arquivo (.pfx ou .p12, com senha) que identifica o CNPJ ou CPF e assina as notas.
NF-e (modelo 55): Nota fiscal eletrônica de mercadorias (modelo 55), autorizada pela SEFAZ do estado do emitente.
Manifestação do destinatário: Resposta do destinatário de uma NF-e à SEFAZ: ciência, confirmação, desconhecimento ou operação não realizada.

Mais em Integrações

Tokens de APICrie chaves para o seu ERP ou script emitir e consultar notas pela API, com escopos, clientes, IPs, limite e validade, e troque-as sem parar a integração.