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
`GET`	`/v1/webhooks/:id`	Detalhe de um webhook
`GET`	`/v1/webhooks/:id/logs`	Histórico de entregas (paginado; filtros `status`, `event`)
`GET`	`/v1/webhooks/:id/logs/:logId`	Detalhe do evento (payload enviado e resposta)
`POST`	`/v1/webhooks/:id/logs/:logId/resend`	Reenvia clonando o log (preserva o histórico original)

Histórico de entregas

Cada disparo gera um log com o request (URL, headers, payload) e a response do seu endpoint (status HTTP, body, duração, tentativas). No painel: API & Webhooks → Eventos em cada webhook. Via API:

Shell

curl -X GET "https://api.emitfy.com/v1/webhooks/WEBHOOK_ID/logs?status=error&limit=20" \
  -H "X-Api-Key: sua-chave" \
  -H "X-Api-Secret: seu-secret"

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

curl -X POST "https://api.emitfy.com/v1/webhooks/WEBHOOK_ID/logs/LOG_ID/resend" \
  -H "X-Api-Key: sua-chave" \
  -H "X-Api-Secret: seu-secret"

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": [],
    "mdfe": []
  }
}

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": "019fc7c4-6560-775b-b422-9ace7707dc00",
    "externalId": "pedido-100",
    "companyId": "019dff1b-1645-7525-b55a-5885d1c8990e",
    "taxId": "00.000.000/0001-00",
    "type": "nfse",
    "status": "authorized",
    "version": 1,
    "amount": 1500,
    "currency": "BRL",
    "issuedAt": "2026-07-06T10:30:00.000Z",
    "createdAt": "2026-07-06T10:28:00.000Z",
    "updatedAt": "2026-07-06T10:30:00.000Z",
    "customer": {
      "name": "João da Silva",
      "document": "123.456.789-00",
      "email": "[email protected]"
    },
    "document": {
      "number": "1234",
      "series": "1",
      "nfse": {
        "seriesKind": "dps",
        "declarationNumber": "1234",
        "verificationCode": "ABCD1234"
      }
    },
    "assets": {
      "pdf": "https://api.emitfy.com/v1/invoices/019fc7c4-6560-775b-b422-9ace7707dc00.pdf",
      "xml": "https://api.emitfy.com/v1/invoices/019fc7c4-6560-775b-b422-9ace7707dc00.xml"
    }
  }
}

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
`mdfe.authorized`	MDF-e autorizado
`mdfe.cancelled`	MDF-e cancelado
`mdfe.rejected`	MDF-e rejeitado na emissão
`mdfe.closed`	MDF-e encerrado

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.