---
updatedAt: 2026-06-05T15:30:05.000Z
agentTools:
projectIndex: https://docs.notagateway.com.br/llms.txt
---
# Webhook
Entenda o que é e como cadastrar um webhook para ser notificado das mudanças de status das suas notas fiscais
## O que é Webhook?
*Webhooks* permitem que sistemas externos recebam notificações de todos os eventos que ocorrem na API.
Quando um evento acontece, a API envia uma requisição HTTP (POST) para a *URL* configurada no *webhook* com as informações relativas ao evento.
Como o processamento de NFS-e ocorre de forma assíncrona, o webhook serve como um mecanismo para notificar o sistema de origem quando ocorre um evento na requisição (Ex: negada, cancelada, cancelamento negado e autorizada)
Ao receber a notificação, o sistema integrado a API pode executar diversas tarefas, dependendo do seu objetivo.
## Eventos que notificam seu sistema:
Seu sistema será notificado sempre que uma nota fiscal mudar para um dos status abaixo:
• **Autorizada** - Nota fiscal foi autorizada pelo órgão responsável;\
• **Negada** - Nota fiscal foi negada pelo órgão responsável;\
• **Cancelada** - O cancelamento da nota fiscal foi autorizado pelo órgão responsável;\
• **CancelamentoNegado** - O cancelamento da nota fiscal foi rejeitado pelo órgão responsável;
O valor em negrito representa o status que será retornado no parâmetro **"nfeStatus"**.
> ❗️ Parâmetro "nfeMotivoStatus"
>
> Este parâmetro só retorna diferente de *null* nos seguintes status:
>
> • "nfeStatus": "Negada",\
> • "nfeStatus": "CancelamentoNegado",
Os dados do POST de notificação variam por tipo de nota fiscal.
Exemplo de retorno de uma NFS-e:
```json WEBHOOK - NFS-e
{
"tipo": "NFS-e",
"empresaId": "string",
"nfeId": "string",
"nfeIdExterno": "string",
"nfeStatus": "string",
"nfeMotivoStatus": "string",
"nfeLinkPdf": "http://api.notagateway.com.br/file/(...)/pdf",
"nfeLinkXml": "http://api.notagateway.com.br/file/(...)/xml",
"nfeNumero": "string",
"nfeCodigoVerificacao": "string",
"nfeNumeroRps": "string",
"nfeSerieRps": "string",
"nfeDataCompetencia": "date"
}
```
**Entenda abaixo o significado de cada atributo no Webhook:**
| Campo | Descrição | |
| :------------------- | :--------------------------------------------------------------------------------- | :- |
| tipo | Tipo de nota fiscal que está sendo emitida. | |
| empresaId | Identificador da empresa associada à nota fiscal que gerou a notificação. | |
| nfeId | Identificador interno da nota fiscal na Nota Gateway | |
| nfeIdExterno | Identificador da nota fiscal definido pelo seu sistema no momento da emissão. | |
| nfeStatus | Status final em que se encontra a nota fiscal. | |
| nfeMotivoStatus | Razão pela qual a nota fiscal está com o status atual. | |
| nfeLinkPdf | Link público para o download em PDF da nota fiscal (nota autorizada ou cancelada). | |
| nfeLinkXml | Link público para o download em XML da nota fiscal (nota autorizada ou cancelada). | |
| nfeNumero | Número da nota fiscal no município. | |
| nfeCodigoVerificacao | Código de verificação, quando aplicável. | |
| nfeNumeroRps | Número de RPS (Recibo Provisório de Serviço) da nota fiscal. | |
| nfeSerieRps | Número de série da nota fiscal. | |
| nfeDataCompetencia | Data de competência da nota fiscal. | |
## Como cadastrar o Webhook:
Pelo painel da Nota Gateway, acesse o menu **Webhooks** ➟ **Novo webhook**:
**Entenda o significado de cada campo:**
• **Url**\
Insira neste campo o link direto para a página do seu sistema que será notificada;
• **Content-Type**\
Escolha o formato que o Gateway deve utilizar para comunicar com seu sistema (JSON ou XML);
• **Token**\
Se desejar, você pode especificar um *token*, ou seja, um código ou frase de sua preferência no cadastro de seu webhook.
Essa informação será enviada pelo Gateway em cada notificação para o seu link cadastrado, dessa forma, você consegue garantir que a requisição (POST) está realmente sendo enviada pela Nota Gateway
O token de autenticação do webhook fica no cabeçalho da requisição, mais especificamente, no item "x-token".
> 📘 Exemplo de envio de um token no headers
>
> "headers": \{ "x-token": "Token webhook", "content-type": "application/json; charset=utf-8"}
**Observações:**
* O payload do webhook fornece o status e os detalhes do processo de emissão da NFS-e.
* Para NFS-es autorizadas, são incluídos links para download do PDF e do XML.
* NFS-es negadas não incluem links para download do PDF ou do XML, pois a emissão não foi concluída.
## Fluxo de retentativa de envio em caso de falha
Se seu sistema apresentar instabilidades ou estiver fora do ar, o **Gateway tentará lhe enviar o webhook de notificação até receber o status "HTTP 200"**, que indica que o webhook foi recebido e tratado com sucesso.
**Serão realizadas 15 tentativas com intervalos de tempo progressivos entre cada uma delas, totalizando, em média, 4 horas.**