Webhook

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:

{
    "tipo": "NFS-e",
    "empresaId": "string",
    "nfeId": "string",
    "nfeIdExterno": "string",
    "nfeStatus": "string",
    "nfeMotivoStatus": "string",
    "nfeLinkPdf": "http://api.enotasgw.com.br/file/(...)/pdf",
    "nfeLinkXml": "http://api.enotasgw.com.br/file/(...)/xml",
    "nfeNumero": "string",
    "nfeCodigoVerificacao": "string",
    "nfeNumeroRps": "string",
    "nfeSerieRps": "string",
    "nfeDataCompetencia": "date"
}

Entenda abaixo o significado de cada atributo no Webhook:

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.