Ir para o conteúdo

OUT1515% off na primeira cobrança com o cupom OUT15.15% off na 1ª cobrançaVer planos

Webhooks · NFS-e, NF-e, CT-e e MDF-e

A nota mudou de status.
O seu sistema já sabe.

Autorizada, rejeitada, cancelada ou encerrada: a Emitfy avisa a sua URL em cada mudança, com o documento no payload, assinatura HMAC e histórico de entregas com reenvio. Sem polling. Em todos os planos.

  • Assinatura HMAC-SHA256
  • Retentativa automática
  • Reenvio pelo histórico
POST https://seu-sistema.com/webhooks/emitfy
X-Emitfy-Signature: t=1793240706,v1=9f2c…e81a
  1. nfse.authorized200142 ms
  2. nfe.authorized20098 ms
  3. cte.authorized50330 s
  4. cte.authorized nova tentativa200211 ms
  5. mdfe.closed20087 ms
Histórico de entregas ilustrativo.
Eventos
13 em 4 documentos
Escopo
A conta inteira
Assinatura
HMAC-SHA256
Headers
Os seus, por webhook
Gestão
API, painel e MCP

Catálogo de eventos

13 eventos, você escolhe quais ouvir.

Cada webhook assina só os eventos que interessam ao seu sistema.

  • NFS-e events.invoice

    • nfse.authorized
    • nfse.rejected
    • nfse.cancelled

    Nota de serviço autorizada, rejeitada ou cancelada, com PDF e XML no payload.

  • NF-e events.invoice

    • nfe.authorized
    • nfe.rejected
    • nfe.cancelled

    Nota de produto, com chave de acesso, PDF e XML quando autorizada.

  • CT-e events.cte

    • cte.authorized
    • cte.rejected
    • cte.cancelled

    Conhecimento de transporte, com número, chave ou o motivo da rejeição.

  • MDF-e events.mdfe

    • mdfe.authorized
    • mdfe.rejected
    • mdfe.cancelled
    • mdfe.closed

    Manifesto da viagem, incluindo o encerramento.

NFC-e ainda não tem evento de webhook: o status fica em GET /nfce/{id} e /events. Veja a API de NFC-e.

Na prática

Receber, conferir, reenviar.

O envelope de cada entrega, a verificação da assinatura, o cadastro e o histórico.

POST seu endpoint
// O que chega no seu endpoint
POST https://seu-sistema.com/webhooks/emitfy
Content-Type: application/json
User-Agent: Emitfy/1.0.0
X-Emitfy-Signature: t=1793240706,v1=9f2c…e81a
Authorization: Bearer seu-token   // header seu, opcional

{
  "id": "evt_…",
  "event": "nfse.authorized",
  "createdAt": "2026-10-28T14:32:10.000Z",
  "data": {
    "id": "…",
    "externalId": "venda-48213",
    "type": "nfse",
    "status": "authorized",
    …,
    "assets": { "pdf": "https://api.emitfy.com/…", "xml": "https://api.emitfy.com/…" }
  }
}
como ler
// data = o mesmo recurso da API
// (GET /v1/companies/{id}/invoices/{id})

// Campos sem valor não vêm no payload:
// trate ausência como "não se aplica".

// Responda 2xx rápido e processe depois.

CT-e e MDF-e usam o mesmo envelope (id, event, createdAt, data), com os dados do documento.

Uma entrega

Do evento ao seu 2xx, com rastro.

  1. Evento

    O status muda

    SEFAZ, prefeitura ou Sefin Nacional respondem e a nota muda de status.

  2. Entrega

    POST assinado

    Payload com o documento, os seus headers e o X-Emitfy-Signature.

  3. Falhou?

    Nova tentativa

    Resposta diferente de 2xx: a Emitfy tenta de novo, com intervalos crescentes.

  4. Histórico

    Tudo registrado

    Request, response e tentativas guardados, com reenvio quando você quiser.

Antes de integrar

O que o time de backend pergunta.

alguém mandar uma chamada falsa?

Sem o segredo do webhook não dá para gerar o X-Emitfy-Signature. O carimbo de tempo protege contra replay.

o segredo vazar?

Gere outro com POST /v1/webhooks/{id}/signing-secret: o anterior deixa de valer na hora.

o meu endpoint pedir autenticação própria?

Cadastre os seus headers no webhook, como um Authorization. Eles vão em toda entrega.

eu perder um evento?

Filtre o histórico por status=error e reenvie a entrega. O log original fica preservado.

a URL for da rede interna?

A URL precisa ser pública: endereços internos, loopback e de metadados são bloqueados por segurança.

eu preferir configurar por um agente?

Pelo MCP, um agente de IA compatível cria, lista e ativa webhooks em português.

Ver o MCP

Perguntas frequentes

Dúvidas sobre webhooks

Quais eventos de webhook a Emitfy envia?

NFS-e e NF-e: authorized, rejected e cancelled. CT-e: authorized, rejected e cancelled. MDF-e: authorized, rejected, cancelled e closed. Você escolhe, por webhook, quais eventos quer receber.

Como sei que a chamada veio mesmo da Emitfy?

Toda entrega leva o header X-Emitfy-Signature, com o HMAC-SHA256 do corpo bruto e um carimbo de tempo, calculado com o segredo do webhook. Recalcule no seu servidor, compare em tempo constante e rejeite carimbos com mais de 5 minutos.

E se o meu endpoint estiver fora do ar?

Se a resposta não for 2xx, a Emitfy tenta de novo com intervalos crescentes. Cada tentativa fica no histórico de entregas, e qualquer entrega pode ser reenviada pela API ou pelo painel.

Preciso de um webhook por empresa?

Não. O webhook pertence à conta e vale para todas as empresas da assinatura. Use o id e o externalId do payload para ligar o evento ao seu registro.

A NFC-e tem webhook?

Ainda não há evento de webhook para a NFC-e. O status fica na consulta da nota (GET /nfce/{id}) e na linha do tempo (GET /nfce/{id}/events).

Em qual plano tenho webhooks?

Webhooks fazem parte da API, incluída em todos os planos e no período gratuito de 10 notas.

Webhooks na Emitfy

Pare de perguntar se a nota saiu.

Crie a conta sem cartão, cadastre a sua URL e receba o primeiro evento com as 10 notas grátis.