Webhooks

A Emitfy notifica as URLs configuradas quando o status de uma nota fiscal muda. Você pode cadastrar vários webhooks na assinatura — cada um com URL, eventos e headers próprios. Os eventos cobrem todas as empresas da assinatura; o payload inclui companyId e taxId (CNPJ) para identificar a origem. Configure no painel (Painel → API & Webhooks) ou via API.

Gerenciar via API

Prefixo: /v1/webhooks. Autenticação com X-Api-Key / X-Api-Secret da conta (sem companyId na URL).

Método	Rota	Descrição
`GET`	`/v1/webhooks`	Lista os webhooks da assinatura
`POST`	`/v1/webhooks`	Cria um novo webhook
`PUT`	`/v1/webhooks/:id`	Atualiza URL, nome, eventos ou headers
`PATCH`	`/v1/webhooks/:id/active`	Ativa ou desativa (`{ "active": true }`)
`DELETE`	`/v1/webhooks/:id`	Remove o webhook

Body de criação / atualização

JSON

{
  "name": "Meu ERP",
  "url": "https://seu-sistema.com/webhooks/emitfy",
  "headers": [
    { "key": "Authorization", "value": "Bearer seu-token" }
  ],
  "events": {
    "invoice": [
      "nfse.authorized",
      "nfse.cancelled",
      "nfse.rejected",
      "nfe.authorized",
      "nfe.cancelled",
      "nfe.rejected"
    ],
    "cte": []
  }
}

Exemplo — listar

Shell

curl -X GET "https://api.emitfy.com/v1/webhooks" \
  -H "X-Api-Key: sua-chave" \
  -H "X-Api-Secret: seu-secret"

Exemplo — criar

Shell

curl -X POST "https://api.emitfy.com/v1/webhooks" \
  -H "X-Api-Key: sua-chave" \
  -H "X-Api-Secret: seu-secret" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Meu ERP",
    "url": "https://seu-sistema.com/webhooks/emitfy",
    "events": {
      "invoice": ["nfse.authorized", "nfe.authorized"],
      "cte": []
    }
  }'

Payload

JSON

{
  "id": "01JXEVENT...",
  "event": "nfse.authorized",
  "createdAt": "2026-07-06T10:30:00.000Z",
  "data": {
    "id": "01JXINVOICE...",
    "saleId": "01JXSALE...",
    "externalId": "pedido-100",
    "companyId": "01JXCOMPANY...",
    "taxId": "00.000.000/0001-00",
    "status": "authorized",
    "type": "nfse",
    "amount": 1500.0,
    "invoiceNumber": "001234",
    "pdfUrl": "https://api.emitfy.com/v1/...",
    "xmlUrl": "https://api.emitfy.com/v1/...",
    "issuedAt": "2026-07-06T10:30:00.000Z",
    "createdAt": "2026-07-06T10:28:00.000Z",
    "updatedAt": "2026-07-06T10:30:00.000Z"
  }
}

Eventos disponíveis

Evento	Descrição
`nfse.authorized`	NFS-e autorizada
`nfse.cancelled`	NFS-e cancelada
`nfse.rejected`	NFS-e rejeitada na emissão
`nfe.authorized`	NF-e autorizada
`nfe.cancelled`	NF-e cancelada
`nfe.rejected`	NF-e rejeitada na emissão
`cte.authorized`	CT-e autorizado (quando habilitado)
`cte.cancelled`	CT-e cancelado
`cte.rejected`	CT-e rejeitado na emissão

Headers customizados

No cadastro do webhook você pode adicionar headers HTTP (ex.: Authorization) que a Emitfy envia em cada notificação, além de Content-Type e User-Agent: Emitfy/1.0.0.

Retentativa

Se sua URL retornar um status HTTP diferente de 2xx, a Emitfy tentará reenviar o evento até 5 vezes com backoff exponencial.