---
title: "Versionamento do payload de webhook — NFS-e"
description: "Diferença entre as versões v1 e v2 do payload de webhook de NFS-e e como cada empresa é versionada."
source_url: https://nfe.io/docs/distribuicao-nfse-inbound-versionamento-webhook/
last_updated: 2026-07-30
---

# Versionamento do payload de webhook — NFS-e

O formato do payload de webhook de NFS-e é versionado **por empresa**, no campo `webhookVersion` da configuração.

## v1 × v2

| Aspecto | v1 | v2 (padrão atual) |
|---|---|---|
| Campo `type` | dentro de `document` | na **raiz** do envelope (alinha com NF-e/CT-e) |
| Tributos | campo monolítico `taxBreakdown` | reorganizado em `federalServiceCode`, `municipalServiceCode`, `amounts` e **`taxes`** (com IBS/CBS) |

O **valor** de `type` (`serviceInvoice`, `serviceInvoiceEvent`, `unknown`) é o mesmo em v1 e v2 — só a posição do campo no envelope muda entre as versões.

## Como cada empresa é versionada

- Empresas **novas** são criadas em **v2**.
- Empresas anteriores ao versionamento (`webhookVersion = 0`, ex.: integrações legadas) permanecem em **v1** — **não há migração automática**. Para migrar, recrie a configuração.
- Documento órfão (sem empresa configurada) cai em **v1** por segurança.

:::caution `webhookVersion` não é exposto na API
Verificamos na plataforma que o `GET .../inbound/nfse/details` **não retorna** o campo `webhookVersion` — ele é um atributo interno por empresa. Para saber em qual versão sua empresa está (ou migrar para v2), trate pela forma do payload recebido ou confirme com o suporte. Empresas criadas recentemente já nascem em v2.
:::

## Veja também

- [Webhook — eventos](./webhook-events.md)
- [Reforma Tributária (RTC)](../../comum/reforma-tributaria-rtc.md)