Configurar webhook
Receita para configurar o endpoint de webhook que receberá notificações de NF-e e CT-e recebidos.
Sumário
- O que é um Webhook
- Como Configurar
- Fluxo do webhook
- Formato do Payload
- Respondendo ao Webhook
- Validando a Autenticidade (HMAC)
- Reprocessar um Webhook
O que é um Webhook
Um webhook é uma notificação automática que enviamos para o seu sistema assim que um evento acontece — como quando uma NF-e nova é recebida.
Funciona como um "aviso automático": em vez de você ficar perguntando periodicamente "chegou algum documento novo?", nós avisamos você no momento exato em que algo acontece.
Como Configurar
- Acesse o Painel nfe.io → Empresas → {sua empresa} → Webhooks
- Cadastre a URL HTTPS do seu endpoint
- Ative o inbound (ver Ativar via API) com
WebhookVersion: 2 - Configure o Webhook Secret (32–64 caracteres ASCII) para validação HMAC
Fluxo do webhook
Formato do Payload
Quando um documento é recebido, fazemos um POST para sua URL. O corpo vem embrulhado num envelope {"body": {...}}, e o tipo de evento chega no header X-Hook-Event (product_invoice_inbound ou transportation_invoice_inbound) e no campo body.action (issued_successfully, event_raised_successfully, entre outros):
{
"body": {
"action": "issued_successfully",
"company": {
"id": "comp_123",
"federalTaxNumber": "98765432000100"
},
"accessKey": "35240112345678000195550010000012341234567890",
"nsu": "21825",
"type": "productInvoice",
"issuedOn": "2024-03-15T10:00:00Z",
"totalInvoiceAmount": "1500.00",
"issuer": {
"federalTaxNumber": "12345678000195",
"name": "Fornecedor LTDA"
},
"buyer": {
"federalTaxNumber": "98765432000100",
"name": "Minha Empresa S.A."
}
}
}
A tabela completa de X-Hook-Event/body.action e o payload de campos por completo estão em Webhook events + validação HMAC.
Respondendo ao Webhook
Seu endpoint deve retornar HTTP 200 em até 30 segundos. Se não retornar 200, tentaremos novamente com backoff exponencial por até 24 horas.
# Exemplo em Python (Flask)
from flask import Flask, request, jsonify
app = Flask(__name__)
@app.route('/webhooks/nfeio', methods=['POST'])
def receive_nfe():
envelope = request.json
body = envelope['body']
if request.headers.get('X-Hook-Event') == 'product_invoice_inbound' and body['action'] in ('issued_successfully', 'outbound_successfully'):
access_key = body['accessKey']
# Processar o documento...
save_to_database(body)
return jsonify({"status": "ok"}), 200
Validando a Autenticidade (HMAC)
A NFE.io assina cada POST com HMAC-SHA1 sobre o body bruto e envia o resultado no header x-hub-signature (formato sha1=<HEX MAIÚSCULO>). A validação é obrigatória — sem isso, qualquer um que descobrir a URL do seu endpoint pode forjar requisições.
O contrato canonical (header, algoritmo, encoding, vetor de teste e implementações de referência em 5 linguagens) está em Webhook events + validação HMAC.
Reprocessar um Webhook
Se precisar receber novamente o webhook de um documento específico:
POST /v2/companies/{company_id}/inbound/productinvoices/{access_key}/processwebhook
Authorization: ApiKey {api_key}