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 (inclui signingSecret) |
POST | /v1/webhooks/:id/signing-secret | Gera um novo segredo de assinatura (o anterior deixa de valer na hora) |
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:
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
{
"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
curl -X GET "https://api.emitfy.com/v1/webhooks" \
-H "X-Api-Key: sua-chave" \
-H "X-Api-Secret: seu-secret"Exemplo — criar
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
{
"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.
Assinatura (HMAC)
Toda entrega leva o header X-Emitfy-Signature: t=<unix>,v1=<hex>, onde v1 é o HMAC-SHA256, com o segredo do webhook, de <t>.<corpo bruto>. O segredo (whsec_…) volta no POST /v1/webhooks, no GET /v1/webhooks/:id e no painel (editar webhook → Assinatura). Webhooks criados antes da assinatura recebem um segredo automaticamente.
Para validar: recalcule o HMAC sobre o corpo exatamente como recebido (antes de fazer parse do JSON), compare em tempo constante e rejeite t com mais de 5 minutos de diferença (proteção contra replay). Cada tentativa é assinada de novo, com t atual.
import { createHmac, timingSafeEqual } from 'node:crypto'
// rawBody: corpo cru da requisição (string), header: valor de X-Emitfy-Signature
export function isValidEmitfySignature(rawBody: string, header: string, secret: string) {
const parts = Object.fromEntries(header.split(',').map((p) => p.trim().split('=')))
const t = Number(parts.t)
if (!Number.isInteger(t) || Math.abs(Date.now() / 1000 - t) > 300) return false
const expected = createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex')
const received = String(parts.v1 ?? '')
return (
received.length === expected.length &&
timingSafeEqual(Buffer.from(expected, 'hex'), Buffer.from(received, 'hex'))
)
}Retentativa
Se sua URL retornar um status HTTP diferente de 2xx, a Emitfy tentará reenviar o evento até 5 vezes com backoff exponencial.