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

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 e ambos os webhooks de retorno da API V2 (NF-e e NFC-e) são bastante similares.

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.

Exemplo WEBHOOK - NF-e

{
    "tipo": "NF-e",
    "empresaId": "string",
    "nfeId": "001",
    "nfeStatus": "Autorizada",
    "nfeMotivoStatus": null,
    "nfeLinkDanfe": "http://api.enotasgw.com.br/file/(...)/pdf",
    "nfeLinkXml": "http://api.enotasgw.com.br/file/(...)/xml",
    "nfeNumero": "123",
    "nfeSerie": "1",
    "nfeChaveAcesso": "08764980057334953516065001000000691967411517",
    "nfeDataEmissao": "2017-01-02T17:20:32Z",
    "nfeDataAutorizacao": "2017-01-02T17:21:07Z",
    "nfeNumeroProtocolo": "353150000119390",
    "nfeDigestValue": "ssiUjiiOQkD2UGw"
}

Exemplo WEBHOOK - NFC-e

O campo "nfeLinkConsultaPorChaveAcesso" é exclusivo das NFC-e, por ser uma especificação das SEFAZ estaduais.

{
    "tipo": "NFC-e",
    "empresaId": "string",
    "nfeId": "001",
    "nfeStatus": "Autorizada",
    "nfeMotivoStatus": null,
    "nfeLinkDanfe": "http://api.enotasgw.com.br/file/(...)/pdf",
    "nfeLinkXml": "http://api.enotasgw.com.br/file/(...)/pdf",
    "nfeLinkConsultaPorChaveAcesso": "http://sistemas.sefaz.am.gov.br/nfceweb/formConsulta.do",
    "nfeNumero": "123",
    "nfeSerie": "1",
    "nfeChaveAcesso": "73349650010000005351606919674115087649800517",
    "nfeDataEmissao": "2017-01-02T17:20:32Z",
    "nfeDataAutorizacao": "2017-01-02T17:21:07Z",
    "nfeNumeroProtocolo": "353150000119390",
    "nfeDigestValue": "ssiUjiiOQkD2UGw"
}

❗️

Campo "nfeMotivoStatus"

Esse campo só retorna diferente de null quando a nota é rejeitada ou denegada.