VISÃO GERAL
O Webhook permite que seu sistema receba notificações em tempo real sempre que um novo evento fiscal for identificado (ex.: cancelamento de NF-e).
O parceiro deve disponibilizar um endpoint HTTP/HTTPS que receberá requisições POST contendo os dados do evento em formato JSON.
Estrutura da Mensagem
{
"Xml": "<procEventoNFe>...</procEventoNFe>",
"Chave": "99999999999999999999999999999999999999999999",
"Mod": 55,
"Mensagem": "Novo cancelamento de NF-e identificado"
}
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| Xml | String | 1-1 | Conteúdo XML do evento |
| Chave | String | 1-1 | Chave de acesso do documento fisca |
| Mod | Int | 1-1 | Modelo do documento fiscal |
| Mensagem | String | 1-1 | Descrição resumida do evento detectado |
Autenticação
As chamadas são feitas com Basic Authentication.
O parceiro deve validar o cabeçalho Authorization da requisição
Exemplo de Header:
Authorization: Basic dXN1YXJpbzpwYXNz
Content-Type: application/json
Onde dXN1YXJpbzpwYXNz é a string Base64 de usuário concatenado com a senha.
Recomendamos fortemente o uso de HTTPS para proteger as credenciais.
REQUISIÇÃO
- Método: POST
- Content-Type: application/json
- Timeout: 10 segundos
TENTATIVAS DE FALHA
Caso o envio da notificação falhe (erro HTTP 4xx/5xx ou indisponibilidade do endpoint):
- Serão realizadas até 5 tentativas no total.
- Cada tentativa será feita com intervalo de 60 minutos entre elas.
- Cada tentativa será registrada no banco de dados, incluindo detalhes do erro, para auditoria e rastreabilidade.
- Se após 5 tentativas a notificação ainda não for entregue, o evento será descartado da fila.
RESPOSTA ESPERADA DO PARCEIRO
O endpoint deve retornar uma resposta HTTP para indicar o status de processamento
EXEMPLO DE RESPOSTA BEM-SUCEDIDA:
HTTP/1.1 200 OK
EXEMPLO DE RESPOSTA COM ERRO:
HTTP/1.1 401 unauthorized
BOAS PRÁTICAS
- Sempre valide a assinatura/credenciais recebidas no Authorization
- Trate idempotência: o mesmo evento pode ser reenviado em caso de falha
- Logue todas as notificações recebidas para auditoria
- Utilize HTTPS