ℹ️

Resumo: o TelcomNFe faz um POST JSON na URL que você cadastrar. Seu endpoint deve responder HTTP 2xx para confirmar o recebimento. Você também pode enviar notification_url por nota na API.

O que é o webhook de notificações

Em vez de ficar consultando o status da nota (polling), o seu sistema recebe um aviso automático quando algo muda — por exemplo, NFCom submetida ou autorizada.

Item	Detalhe
Onde configurar	Configuração → Integrações → Notificações Webhook
Campo	URL para Notificações (HTTPS recomendado)
Eventos típicos	Submissão e autorização da NFCom
Alternativa por API	Informe `notification_url` no payload da emissão

Acessar Configuração do Sistema

No menu lateral, clique em Configuração.

Animação: acessando Configuração no menu lateral

Menu lateral → Configuração

Abrir a aba Integrações

Selecione a aba Integrações. Nela ficam o token da API e a seção Notificações Webhook.

Configuração → Integrações

Informar a URL do webhook

Em Notificações Webhook, preencha URL para Notificações com o endpoint do seu sistema (ex.: https://sua-api.com.br/webhook/nfcom).

⚠️

Use preferencialmente HTTPS e uma URL pública acessível pela internet. Endpoints locais (localhost) não recebem as notificações do TelcomNFe.

Campo URL para Notificações

Testar a URL

Clique em Testar. O TelcomNFe envia uma requisição de verificação para a URL informada e mostra o resultado (sucesso ou erro) com o tempo de resposta.

Botão Testar

Salvar alterações

Clique em Salvar Alterações para gravar a URL padrão da empresa. A partir daí, as notificações usam esse endereço (salvo quando a emissão informar outra notification_url).

Salvar Alterações

Exemplo de payload recebido

Seu endpoint recebe um POST com JSON. Exemplo simplificado após autorização:

{
  "event": "nfcom_authorized",
  "timestamp": "2026-09-08T15:00:00.000Z",
  "message": "NFCom foi autorizada pela SEFAZ",
  "nfcom": {
    "id": "uuid-da-nfcom",
    "number": 123456,
    "series": "1",
    "model": 62,
    "status": "SUBMITTED",
    "nfcom_key": "3525...",
    "protocol_number": "13525...",
    "environment": "producao"
  }
}

Detalhes técnicos e headers (incluindo assinatura) estão na página da API.

Boas práticas

Responda HTTP 2xx rapidamente; processe a lógica em fila se precisar.
Trate o mesmo evento mais de uma vez com idempotência (retries existem).
Registre logs com id / chave da NFCom para auditoria.
Para autenticação das chamadas de saída do seu ERP para o TelcomNFe, use o Token de Integração.

← Token de Integração Documentação da API →

Como usar o Webhook de notificações