Pular para o conteúdo
Docs

Catálogo de eventos de webhook

Atualizado em

Nesta página

Webhooks avisam o seu sistema quando algo muda na Emitra, sem você precisar consultar a API em loop. Cada evento chega como um POST JSON assinado para a URL que você cadastrou.

Você cadastra endpoints no painel (Notas › Automação › Integrações › Webhooks) ou pela API em /integracao/webhooks, e escolhe quais eventos cada endpoint recebe.

Envelope comum#

Todo evento tem o mesmo envelope. O conteúdo específico do evento fica em data.

Campo Tipo Descrição
id string (UUID) Identificador estável do evento. Use para deduplicar.
type string Tipo do evento, como nfse.authorized.
created_at string (ISO 8601) Quando o evento aconteceu, com fuso.
company_id string (UUID) Empresa a que o evento pertence.
is_test boolean true para eventos gerados por chaves de teste (sandbox).
data object Dados do evento. Varia por type.
Envelope
{
  "id": "9d8c7b6a-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
  "type": "nfse.authorized",
  "created_at": "2026-11-11T10:15:33-03:00",
  "company_id": "0b1e2c3d-4f5a-4b6c-8d7e-9f0a1b2c3d4e",
  "is_test": true,
  "data": {}
}

Os headers de cada entrega (X-Emitra-Event, X-Emitra-Delivery, X-Emitra-Timestamp e X-Emitra-Signature) estão em Verificar a assinatura.

Lista de eventos#

Evento Quando dispara
dps.queued A DPS foi aceita para processamento e está na fila de emissão.
nfse.authorized A Sefin Nacional autorizou a nota.
nfse.rejected A Sefin Nacional rejeitou a DPS por regra de negócio ou de schema.
nfse.canceled O evento de cancelamento da nota foi registrado.
nfse.replaced A nota foi substituída por uma nova.
nfse.imported Uma importação de NFS-e emitidas fora da Emitra terminou.
recurring.execution_failed Uma execução de emissão recorrente falhou.
recurring.execution_skipped Uma execução recorrente foi pulada (bloqueio, cota ou certificado).
batch.completed Um lote de emissão terminou de processar.
export.completed Uma exportação ficou pronta para download.
accountant_delivery.sent O envio automático ao contador foi feito.
certificate.expiring O certificado A1 vence em 30, 15, 7 ou 1 dia.
subscription.past_due A assinatura da empresa entrou em atraso.
subscription.blocked A emissão foi bloqueada por inadimplência.

Ciclo fiscal#

dps.queued#

dps.queued
{
  "id": "2a1b0c9d-8e7f-4a6b-9c5d-4e3f2a1b0c9d",
  "type": "dps.queued",
  "created_at": "2026-11-11T10:15:30-03:00",
  "company_id": "0b1e2c3d-4f5a-4b6c-8d7e-9f0a1b2c3d4e",
  "is_test": true,
  "data": {
    "nfse_id": "3c9b7e1a-6d42-4f8e-a0b3-7e2f5d1c9a84",
    "status": "queued",
    "origem": "api",
    "external_ref": "pedido-2026-11-0001",
    "id_dps": "DPS355030821122233300018100900000000000000042",
    "competencia": "2026-11-10",
    "valor_servico": "1500.00"
  }
}

nfse.authorized#

nfse.authorized
{
  "id": "9d8c7b6a-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
  "type": "nfse.authorized",
  "created_at": "2026-11-11T10:15:33-03:00",
  "company_id": "0b1e2c3d-4f5a-4b6c-8d7e-9f0a1b2c3d4e",
  "is_test": true,
  "data": {
    "nfse_id": "3c9b7e1a-6d42-4f8e-a0b3-7e2f5d1c9a84",
    "status": "authorized",
    "external_ref": "pedido-2026-11-0001",
    "numero_nfse": "42",
    "chave_acesso": "35503082211222333000181000000000004226114829130573",
    "id_dps": "DPS355030821122233300018100900000000000000042",
    "competencia": "2026-11-10",
    "emitida_em": "2026-11-11T10:15:32-03:00",
    "tomador": {
      "id": "5f0c2a8e-1b7d-4c3e-9a51-2d6e8f4b7c10",
      "nome": "Padaria Silva Ltda",
      "documento": "11444777000161"
    },
    "valores": {
      "valor_servico": "1500.00",
      "aliquota_iss": "2.00",
      "valor_iss": "30.00",
      "valor_liquido": "1500.00"
    },
    "links": {
      "xml": "/api/v1/integracao/nfse/3c9b7e1a-6d42-4f8e-a0b3-7e2f5d1c9a84/xml",
      "pdf": "/api/v1/integracao/nfse/3c9b7e1a-6d42-4f8e-a0b3-7e2f5d1c9a84/pdf"
    }
  }
}

nfse.rejected#

nfse.rejected
{
  "id": "4b3a2918-7f6e-4d5c-8b4a-3f2e1d0c9b8a",
  "type": "nfse.rejected",
  "created_at": "2026-11-11T10:15:33-03:00",
  "company_id": "0b1e2c3d-4f5a-4b6c-8d7e-9f0a1b2c3d4e",
  "is_test": true,
  "data": {
    "nfse_id": "3c9b7e1a-6d42-4f8e-a0b3-7e2f5d1c9a84",
    "status": "rejected",
    "external_ref": "pedido-2026-11-0001",
    "id_dps": "DPS355030821122233300018100900000000000000042",
    "rejeicao": {
      "codigo": "E0617",
      "titulo": "Alíquota não deve ser informada",
      "orientacao": "O município é conveniado: a Sefin aplica a alíquota parametrizada. Deixe a alíquota em branco.",
      "tipo": "municipality",
      "mensagem_oficial": "Mensagem original devolvida pela Sefin Nacional."
    }
  }
}

O campo rejeicao.tipo ajuda a decidir o que fazer. Os valores e o mapa completo de códigos estão em Erros.

nfse.canceled#

nfse.canceled
{
  "id": "6c5b4a39-2817-4f6e-9d5c-4b3a29180f7e",
  "type": "nfse.canceled",
  "created_at": "2026-11-12T09:02:11-03:00",
  "company_id": "0b1e2c3d-4f5a-4b6c-8d7e-9f0a1b2c3d4e",
  "is_test": true,
  "data": {
    "nfse_id": "3c9b7e1a-6d42-4f8e-a0b3-7e2f5d1c9a84",
    "status": "canceled",
    "external_ref": "pedido-2026-11-0001",
    "chave_acesso": "35503082211222333000181000000000004226114829130573",
    "evento": {
      "tipo": "101101",
      "descricao": "Cancelamento de NFS-e",
      "motivo_codigo": "2",
      "motivo_texto": "Serviço não prestado no período contratado.",
      "registrado_em": "2026-11-12T09:02:10-03:00"
    }
  }
}

nfse.replaced#

nfse.replaced
{
  "id": "8e7d6c5b-4a39-4281-9f0e-7d6c5b4a3928",
  "type": "nfse.replaced",
  "created_at": "2026-11-12T11:40:05-03:00",
  "company_id": "0b1e2c3d-4f5a-4b6c-8d7e-9f0a1b2c3d4e",
  "is_test": true,
  "data": {
    "nfse_id": "3c9b7e1a-6d42-4f8e-a0b3-7e2f5d1c9a84",
    "status": "replaced",
    "chave_acesso": "35503082211222333000181000000000004226114829130573",
    "substituta": {
      "nfse_id": "e4a1c7b2-3d5f-4a6e-9b8c-1d2e3f4a5b6c",
      "status": "authorized"
    },
    "evento": {
      "tipo": "105102",
      "descricao": "Cancelamento de NFS-e por Substituição"
    }
  }
}

nfse.imported#

nfse.imported
{
  "id": "1f2e3d4c-5b6a-4798-8a7b-6c5d4e3f2a1b",
  "type": "nfse.imported",
  "created_at": "2026-11-11T16:20:00-03:00",
  "company_id": "0b1e2c3d-4f5a-4b6c-8d7e-9f0a1b2c3d4e",
  "is_test": false,
  "data": {
    "job_id": "c3b2a190-8f7e-4d6c-9b5a-4f3e2d1c0b9a",
    "total_arquivos": 12,
    "importadas": 10,
    "duplicadas": 1,
    "rejeitadas": 1
  }
}

Automação#

recurring.execution_failed#

recurring.execution_failed
{
  "id": "3d2c1b0a-9f8e-4d7c-8b6a-5f4e3d2c1b0a",
  "type": "recurring.execution_failed",
  "created_at": "2026-12-05T07:01:12-03:00",
  "company_id": "0b1e2c3d-4f5a-4b6c-8d7e-9f0a1b2c3d4e",
  "is_test": false,
  "data": {
    "schedule_id": "a9b8c7d6-e5f4-4a3b-8c2d-1e0f9a8b7c6d",
    "execution_id": "b8c7d6e5-f4a3-4b2c-9d1e-0f9a8b7c6d5e",
    "competencia": "2026-12-01",
    "status": "rejected",
    "nfse_id": "3c9b7e1a-6d42-4f8e-a0b3-7e2f5d1c9a84",
    "sefin_codigo": "E0116",
    "sefin_mensagem": "Inscrição municipal obrigatória"
  }
}

recurring.execution_skipped#

recurring.execution_skipped
{
  "id": "5e4d3c2b-1a0f-4e9d-8c7b-6a5f4e3d2c1b",
  "type": "recurring.execution_skipped",
  "created_at": "2026-12-05T07:01:12-03:00",
  "company_id": "0b1e2c3d-4f5a-4b6c-8d7e-9f0a1b2c3d4e",
  "is_test": false,
  "data": {
    "schedule_id": "a9b8c7d6-e5f4-4a3b-8c2d-1e0f9a8b7c6d",
    "execution_id": "c7d6e5f4-a3b2-4c1d-8e0f-9a8b7c6d5e4f",
    "competencia": "2026-12-01",
    "status": "skipped",
    "motivo": "COTA_EXCEDIDA"
  }
}

motivo pode ser TENANT_INADIMPLENTE, COTA_EXCEDIDA ou CERTIFICADO_VENCIDO.

batch.completed#

batch.completed
{
  "id": "7a6b5c4d-3e2f-4a1b-9c0d-8e7f6a5b4c3d",
  "type": "batch.completed",
  "created_at": "2026-11-11T14:32:40-03:00",
  "company_id": "0b1e2c3d-4f5a-4b6c-8d7e-9f0a1b2c3d4e",
  "is_test": false,
  "data": {
    "batch_id": "d6e5f4a3-b2c1-4d0e-9f8a-7b6c5d4e3f2a",
    "status": "done",
    "total_linhas": 120,
    "autorizadas": 117,
    "rejeitadas": 3,
    "relatorio_disponivel": true
  }
}

Exportação e contador#

export.completed#

export.completed
{
  "id": "0a9b8c7d-6e5f-4a4b-8c3d-2e1f0a9b8c7d",
  "type": "export.completed",
  "created_at": "2026-12-01T08:05:00-03:00",
  "company_id": "0b1e2c3d-4f5a-4b6c-8d7e-9f0a1b2c3d4e",
  "is_test": false,
  "data": {
    "export_id": "7e6d5c4b-3a29-4180-9f7e-6d5c4b3a2918",
    "status": "done",
    "periodo_inicio": "2026-11-01",
    "periodo_fim": "2026-11-30",
    "linhas": 148,
    "expira_em": "2026-12-08T08:05:00-03:00"
  }
}

O link de download não vai no webhook. Ele é gerado no painel e vale 24 horas.

accountant_delivery.sent#

accountant_delivery.sent
{
  "id": "2c3d4e5f-6a7b-4c8d-9e0f-1a2b3c4d5e6f",
  "type": "accountant_delivery.sent",
  "created_at": "2026-12-05T08:00:30-03:00",
  "company_id": "0b1e2c3d-4f5a-4b6c-8d7e-9f0a1b2c3d4e",
  "is_test": false,
  "data": {
    "delivery_id": "e5f4a3b2-c1d0-4e9f-8a7b-6c5d4e3f2a1b",
    "competencia": "2026-11-01",
    "modo": "link",
    "destinatarios": 2,
    "export_id": "7e6d5c4b-3a29-4180-9f7e-6d5c4b3a2918"
  }
}

Conta#

certificate.expiring#

certificate.expiring
{
  "id": "4e5f6a7b-8c9d-4e0f-9a1b-2c3d4e5f6a7b",
  "type": "certificate.expiring",
  "created_at": "2026-11-11T08:00:00-03:00",
  "company_id": "0b1e2c3d-4f5a-4b6c-8d7e-9f0a1b2c3d4e",
  "is_test": false,
  "data": {
    "certificate_id": "f4a3b2c1-d0e9-4f8a-9b7c-6d5e4f3a2b1c",
    "valido_ate": "2026-12-11T23:59:59-03:00",
    "dias_restantes": 30
  }
}

O payload nunca contém o arquivo PFX nem a senha do certificado.

subscription.past_due#

subscription.past_due
{
  "id": "6a7b8c9d-0e1f-4a2b-8c3d-4e5f6a7b8c9d",
  "type": "subscription.past_due",
  "created_at": "2026-12-11T00:10:00-03:00",
  "company_id": "0b1e2c3d-4f5a-4b6c-8d7e-9f0a1b2c3d4e",
  "is_test": false,
  "data": {
    "status": "past_due",
    "atraso_desde": "2026-12-10",
    "carencia_ate": "2026-12-15"
  }
}

subscription.blocked#

subscription.blocked
{
  "id": "8c9d0e1f-2a3b-4c4d-9e5f-6a7b8c9d0e1f",
  "type": "subscription.blocked",
  "created_at": "2026-12-16T00:05:00-03:00",
  "company_id": "0b1e2c3d-4f5a-4b6c-8d7e-9f0a1b2c3d4e",
  "is_test": false,
  "data": {
    "status": "blocked",
    "bloqueado_em": "2026-12-16T00:05:00-03:00"
  }
}

Eventos de cobrança nunca trazem dados de cartão. Com a emissão bloqueada, a API recusa emissão, cancelamento e substituição com 403 TENANT_INADIMPLENTE, mas consultas e downloads continuam funcionando.

Próximos passos#

Esta página foi útil?