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.

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",

{
    "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 o significado de cada atributo no Webhook:

• 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 no eNotas 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 (Nota autorizada/cancelada)
Link público para o download PDF da nota fiscal.
• nfeLinkXml (Nota autorizada/cancelada)
Link público para o download XML da nota fiscal.
• nfeNumero
Número da nota fiscal no município.
• nfeCodigoVerificacao
Caso se aplique, representa o código de verificação na prefeitura.
• nfeNumeroRps
Representa o número de RPS (Recibo provisório de Serviço) da nota fiscal.
• nfeSerieRps
Representa a série da nota fiscal.
• nfeDataCompetencia
Data de competência da nota fiscal.

Como cadastrar o Webhook:

Pelo painel do eNotas 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 pelo eNotas 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"}

Dados retornados na notificação:

Os dados do POST de notificação variam por tipo de nota fiscal.

Abaixo há o modelo de WEBHOOK para NFS-e.

Novas tentativas 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.