Ir para o conteúdo

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

Guia

Webhooks da API Emitfy

Como receber webhooks da Emitfy com o status de cada nota: eventos, headers de autenticação, retentativas e a diferença para o webhook de entrada.

Rainer R. · FundadorAtualizado em 2 min de leitura

Dois tipos de webhook

Webhook de saída (Emitfy → seu sistema): notifica eventos de nota. É cadastrado na assinatura, por /v1/webhooks ou no painel em API & Webhooks, com URL, eventos e headers próprios.

Webhook de entrada (venda → Emitfy): é a integração. Hotmart, Kiwify e as demais plataformas, ou o seu sistema pela integração API, enviam a venda para a Emitfy emitir.

Documentação: docs.emitfy.com/webhooks (saída) e docs.emitfy.com/integrations/api-webhook (entrada).

Eventos disponíveis

Lista conforme docs.emitfy.com/webhooks.
DocumentoEventos
NFS-enfse.authorized · nfse.rejected · nfse.cancelled
NF-enfe.authorized · nfe.rejected · nfe.cancelled
CT-ecte.authorized · cte.rejected · cte.cancelled
MDF-emdfe.authorized · mdfe.rejected · mdfe.cancelled · mdfe.closed

Boas práticas no seu endpoint

  • URL HTTPS que aceite o mesmo evento mais de uma vez sem duplicar efeito
  • Header próprio (por exemplo, Authorization) cadastrado no webhook e conferido a cada chamada
  • Responder 2xx rápido e processar o evento em segundo plano
  • Guardar o id da nota e o companyId de cada evento
  • Conferir no painel, em API & Webhooks → Eventos, o request e a resposta de cada disparo

Perguntas frequentes

Como sei que o webhook veio da Emitfy?

No cadastro do webhook você define headers HTTP, como Authorization com um segredo seu. A Emitfy envia esses headers em toda notificação, junto com User-Agent Emitfy/1.0.0. Recuse chamadas sem o seu header.

E se o meu servidor estiver fora do ar?

Se a resposta não for 2xx, a Emitfy reenvia o evento até 5 vezes, com intervalo crescente. Cada tentativa fica registrada no log de eventos do painel.

Os webhooks incluem o XML?

Não. O evento avisa o que aconteceu; XML e PDF são baixados pelos endpoints da nota, como /nfse/{id}/xml.

Preciso de webhook se uso só o painel?

Não. Webhooks servem para sistemas que precisam reagir sozinhos à mudança de status.

Próximo passo

Automatize a emissão fiscal com a Emitfy

Conecte sua plataforma ou use a API REST. 10 notas grátis para testar, sem cartão.