Webhook

A LideraNota avisa o desfecho de cada nota com um POST no endereço de webhook do seu sistema. É o ponto de maior risco da integração: siga as regras abaixo à risca. O contrato do evento está na referência do webhook.

Endereço do webhook e token de webhook

O endereço do webhook precisa ser HTTPS, com certificado TLS válido emitido por autoridade certificadora pública, sem usuário e senha embutidos no endereço, e final: sem redirecionamento de http para https, de barra final ou de domínio. O endereço é um por emitente.

Para começar a receber eventos, informe o endereço e peça o cadastro do endereço do webhook; junto com ele, a LideraNota entrega o token de webhook, mostrado uma única vez. A LideraNota executa este passo: pedir pelo WhatsApp.

Para trocar o endereço do webhook, por exemplo numa mudança de servidor, informe o endereço novo. A LideraNota executa este passo: pedir pelo WhatsApp.

Guarde o token de webhook como o token de acesso: no cofre de segredos ou na configuração protegida do seu sistema, nunca em código-fonte, log ou tela.

Requisição recebida

A LideraNota envia POST no endereço cadastrado, com Content-Type: application/json, o cabeçalho X-Lwnfse-Token e o evento em JSON UTF-8. Exemplo de evento autorizada recebido em https://sistema-do-cliente.example/webhook/nfse:

POST /webhook/nfse HTTP/1.1
Host: sistema-do-cliente.example
Content-Type: application/json
X-Lwnfse-Token: <token-de-webhook>

{
  "eventoId": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f7a8b9",
  "tipo": "autorizada",
  "ocorridoEm": "2026-11-10T14:05:41.123Z",
  "nota": {
    "id": "3f8b2c1a-6d4e-4b7f-9a21-0c5e8d7f6a10",
    "idOperacao": "FAT-1001",
    "loteId": "7c1e9a4b-2f3d-4e8a-b5c6-1d2e3f4a5b6c",
    "status": "autorizada",
    "ambiente": "homologacao",
    "numeroNfse": "123",
    "chaveAcesso": "31062002211222333000181000000000012326110000001234",
    "autorizadaEm": "2026-11-10T14:05:40.000Z",
    "links": {
      "xml": "https://hml.nfse.lideraweb.com/v1/notas/3f8b2c1a-6d4e-4b7f-9a21-0c5e8d7f6a10/xml",
      "danfse": "https://hml.nfse.lideraweb.com/v1/notas/3f8b2c1a-6d4e-4b7f-9a21-0c5e8d7f6a10/danfse"
    }
  }
}

• eventoId: identificador do evento, chave da deduplicação.
• ocorridoEm: instante do evento em UTC, chave da ordenação.
• nota: o mesmo objeto da consulta da nota, com o estado no instante do evento. O conteúdo é congelado na criação do evento, inclusive quando o mesmo evento chega de novo mais tarde; o estado atual é o da consulta.
• Os links são baixados com o token de acesso (Authorization: Bearer), nunca com o token de webhook.

Para testar o receptor do seu sistema antes de cadastrar o endereço, simule a entrega com curl, com URL_WEBHOOK contendo o endereço do seu receptor de teste e TOKEN_WEBHOOK contendo um token de teste configurado nele:

curl -X POST "$URL_WEBHOOK" \
  -H "Content-Type: application/json" \
  -H "X-Lwnfse-Token: $TOKEN_WEBHOOK" \
  --data '{
  "eventoId": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f7a8b9",
  "tipo": "autorizada",
  "ocorridoEm": "2026-11-10T14:05:41.123Z",
  "nota": {
    "id": "3f8b2c1a-6d4e-4b7f-9a21-0c5e8d7f6a10",
    "idOperacao": "FAT-1001",
    "loteId": "7c1e9a4b-2f3d-4e8a-b5c6-1d2e3f4a5b6c",
    "status": "autorizada",
    "ambiente": "homologacao",
    "numeroNfse": "123",
    "chaveAcesso": "31062002211222333000181000000000012326110000001234",
    "autorizadaEm": "2026-11-10T14:05:40.000Z",
    "links": {
      "xml": "https://hml.nfse.lideraweb.com/v1/notas/3f8b2c1a-6d4e-4b7f-9a21-0c5e8d7f6a10/xml",
      "danfse": "https://hml.nfse.lideraweb.com/v1/notas/3f8b2c1a-6d4e-4b7f-9a21-0c5e8d7f6a10/danfse"
    }
  }
}'

Repita a simulação com o mesmo eventoId (o receptor deve responder 2xx sem processar de novo) e com um token diferente (o receptor deve responder 401).

Tipos de evento

• Tipo desconhecido: responda 2xx a qualquer tipo que o seu sistema não conheça e registre o evento. Assim uma versão nova da API, com um tipo novo, não faz a entrega falhar até esgotar as tentativas.
• pendente_intervencao não gera evento: mantenha uma rotina que consulta as notas enviadas há muito tempo sem evento de desfecho.

Verificação do token

• Compare o cabeçalho X-Lwnfse-Token com o token de webhook guardado no seu sistema em tempo constante, com a função de comparação segura da sua linguagem, nunca com a comparação comum de texto, que vaza o tempo da comparação.
• Token ausente ou diferente: responda 401 sem processar. Nunca responda 2xx nesse caso: qualquer 2xx encerra a entrega e o evento se perde. Com 401, a LideraNota tenta de novo.
• Não registre em log o valor recebido nem o esperado.
• A autenticação da origem é o X-Lwnfse-Token, e a LideraNota só envia para endereço HTTPS: não é preciso conferir o IP de origem.

Quando o token de webhook vazar ou precisar ser trocado, peça um novo token de webhook. O anterior deixa de valer na hora, e as novas tentativas de eventos pendentes já saem com o token novo: troque o valor configurado no seu sistema logo em seguida. Eventos recusados com 401 nesse intervalo chegam de novo nas próximas tentativas. A LideraNota executa este passo: pedir pelo WhatsApp.

Deduplicação por eventoId

O mesmo evento pode chegar mais de uma vez: a entrega é repetida depois de tempo esgotado ou falha de rede, inclusive quando o seu sistema respondeu 2xx mas a resposta se perdeu no caminho. Grave os eventoId recebidos, com chave única, e, ao receber um eventoId já gravado, ignore o evento sem erro e responda 2xx.

Ordenação por ocorridoEm

Sob novas tentativas, os eventos podem chegar fora de ordem: um evento mais antigo pode chegar depois de um mais recente da mesma nota (por exemplo autorizada depois de cancelada). Guarde, por nota, o ocorridoEm do último estado aplicado e descarte o evento cujo ocorridoEm é mais antigo que ele, mesmo com eventoId novo. Compare instantes, convertidos para UTC, e não o texto recebido.

Resposta esperada e novas tentativas

• Responda 2xx logo depois de gravar o evento. Não baixe o XML nem o DANFSe e não atualize faturas dentro da requisição do webhook: deixe o processamento para uma fila ou rotina do seu sistema.
• Qualquer status de 200 a 299 conta como entregue; o corpo da resposta é descartado sem leitura.
• Qualquer outra resposta, tempo de resposta acima de 10 segundos ou erro de rede ou TLS gera nova tentativa, com intervalos de 1, 2, 4, 8, 16 e 32 minutos e depois a cada hora, até 24 tentativas, por cerca de um dia.
• Redirecionamento (3xx) nunca é seguido e conta como falha.

Esgotadas as tentativas, a entrega daquele evento para. Enquanto isso, a consulta da nota é o caminho. Corrigido o problema no seu receptor, peça o reenvio dos eventos que falharam, que chegam com o mesmo eventoId. A LideraNota executa este passo: pedir pelo WhatsApp.

Lógica sugerida do receptor

1. Confira o X-Lwnfse-Token em tempo constante; ausente ou diferente, responda 401.
2. Leia o corpo como JSON; corpo inválido, responda 400 e registre o caso.
3. Se o eventoId já foi gravado, responda 2xx sem processar de novo.
4. Grave o evento com o eventoId, o id da nota, o tipo, o ocorridoEm e o corpo recebido.
5. Se o ocorridoEm for mais antigo que o último estado aplicado da nota, marque o evento como descartado; senão, enfileire o processamento.
6. Responda 2xx. Se a gravação falhar, responda 500, para a LideraNota tentar de novo.
7. Na fila do seu sistema, aplique o estado da nota e baixe os documentos com o token de acesso.