---
title: "Configurar webhook do NFe/CTe Inbound"
description: "Como cadastrar o endpoint de webhook, validar a assinatura HMAC e reprocessar notificações para o NFe/CTe Inbound."
source_url: https://nfe.io/docs/distribuicao-nfe-cte-configurar-webhook/
last_updated: 2026-07-30
---

# 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](#o-que-é-um-webhook)
- [Como Configurar](#como-configurar)
- [Fluxo do webhook](#fluxo-do-webhook)
- [Formato do Payload](#formato-do-payload)
- [Respondendo ao Webhook](#respondendo-ao-webhook)
- [Validando a Autenticidade (HMAC)](#validando-a-autenticidade-hmac)
- [Reprocessar um Webhook](#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

1. Acesse o Painel nfe.io → Empresas → \{sua empresa\} → Webhooks
2. Cadastre a URL HTTPS do seu endpoint
3. Ative o inbound (ver [Ativar via API](./ativar-via-api.md)) com `WebhookVersion: 2`
4. Configure o **Webhook Secret** (32–64 caracteres ASCII) para validação HMAC

## Fluxo do webhook

```mermaid
sequenceDiagram
    participant SEFAZ
    participant NFEIO as nfe.io
    participant Voce as Seu sistema
    SEFAZ-->>NFEIO: Documento autorizado
    NFEIO->>NFEIO: Polling NSU + parse XML
    NFEIO->>Voce: POST webhook (x-hub-signature)
    Voce->>Voce: Valida HMAC + processa
    Voce-->>NFEIO: HTTP 200
```

## 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):

```json
{
  "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](../reference/webhook-events.md#eventos).

## 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.

```python
# 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](../reference/webhook-events.md).

## Reprocessar um Webhook

Se precisar receber novamente o webhook de um documento específico:

```http
POST /v2/companies/{company_id}/inbound/productinvoices/{access_key}/processwebhook
Authorization: ApiKey {api_key}
```

## Veja também

- [Webhook events + HMAC](../reference/webhook-events.md)
- [Ativar via API](./ativar-via-api.md)
- [Códigos HTTP e tratamento de erros](../reference/http-errors.md)
- [Endpoints de NF-e](../reference/endpoints-nfe.md)