Pular para o conteúdo
Docs

Referência: Webhooks endpoints

Atualizado em

Nesta página

Um endpoint de webhook é uma URL do seu sistema que recebe os eventos da Emitra. Você pode gerenciá-los pelo painel ou por estas rotas.

Método Rota Escopo
POST /integracao/webhooks webhooks:manage
GET /integracao/webhooks webhooks:manage
PATCH /integracao/webhooks/{id} webhooks:manage
DELETE /integracao/webhooks/{id} webhooks:manage
GET /integracao/webhooks/{id}/entregas webhooks:manage
POST /integracao/webhooks/{id}/testar webhooks:manage

Os eventos disponíveis e o formato do corpo estão no Catálogo de eventos.

O objeto endpoint#

Endpoint
{
  "id": "b7d4e2f1-9c3a-4e8b-8f65-1a2b3c4d5e6f",
  "url": "https://erp.exemplo.com.br/webhooks/emitra",
  "eventos": ["nfse.authorized", "nfse.rejected", "nfse.canceled", "nfse.replaced"],
  "ativo": true,
  "falhas_consecutivas": 0,
  "motivo_desativacao": null,
  "is_test": true,
  "created_at": "2026-11-11T10:20:00-03:00",
  "updated_at": "2026-11-11T10:20:00-03:00"
}
Campo Descrição
url URL de destino. Só https, porta 443
eventos Lista de tipos de evento assinados
ativo false pausa as entregas
falhas_consecutivas Entregas que falharam em sequência. Com 20, o endpoint é desativado sozinho
motivo_desativacao Preenchido quando a Emitra desativou o endpoint
is_test true se criado com chave de teste. Endpoints de teste só recebem eventos de teste

Criar um endpoint#

POST /integracao/webhooks → 201 Created

Campo Tipo Descrição
url string URL https do seu receptor. Obrigatório
eventos lista Tipos de evento. Obrigatório, ao menos um
ativo boolean Padrão true
cURL
curl https://emitra.com.br/api/v1/integracao/webhooks \
  -H "Authorization: Bearer $EMITRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://erp.exemplo.com.br/webhooks/emitra",
    "eventos": ["nfse.authorized", "nfse.rejected", "nfse.canceled", "nfse.replaced"]
  }'

A resposta de criação inclui o campo segredo, usado para verificar a assinatura de cada entrega. Guarde-o como EMITRA_WEBHOOK_SECRET.

URLs recusadas#

Para proteger a sua rede e a nossa, a Emitra recusa URLs que:

  • não são https, ou usam porta diferente de 443;
  • resolvem para IP privado, loopback, link-local ou endereço de metadados de nuvem (169.254.169.254);
  • respondem com redirecionamento (a Emitra não segue redirects).

Listar endpoints#

GET /integracao/webhooks → 200, paginado por cursor.

cURL
curl https://emitra.com.br/api/v1/integracao/webhooks \
  -H "Authorization: Bearer $EMITRA_API_KEY"

Alterar um endpoint#

PATCH /integracao/webhooks/{id} → 200. Use para trocar a URL, os eventos ou reativar um endpoint desativado.

cURL
curl -X PATCH https://emitra.com.br/api/v1/integracao/webhooks/b7d4e2f1-9c3a-4e8b-8f65-1a2b3c4d5e6f \
  -H "Authorization: Bearer $EMITRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "ativo": true, "eventos": ["nfse.authorized", "nfse.rejected", "certificate.expiring"] }'

Reativar um endpoint zera falhas_consecutivas. Corrija o receptor antes, ou ele será desativado de novo.

Remover um endpoint#

DELETE /integracao/webhooks/{id} → 200. As entregas pendentes são descartadas.

cURL
curl -X DELETE https://emitra.com.br/api/v1/integracao/webhooks/b7d4e2f1-9c3a-4e8b-8f65-1a2b3c4d5e6f \
  -H "Authorization: Bearer $EMITRA_API_KEY"

Listar entregas#

GET /integracao/webhooks/{id}/entregas → 200, paginado por cursor. Mostra cada tentativa de entrega dos últimos 90 dias.

cURL
curl "https://emitra.com.br/api/v1/integracao/webhooks/b7d4e2f1-9c3a-4e8b-8f65-1a2b3c4d5e6f/entregas?limit=50" \
  -H "Authorization: Bearer $EMITRA_API_KEY"
Entrega
{
  "id": "f1e2d3c4-b5a6-4978-8a9b-0c1d2e3f4a5b",
  "evento_id": "9d8c7b6a-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
  "tipo": "nfse.authorized",
  "status": "retrying",
  "tentativas": 2,
  "proxima_tentativa_em": "2026-11-11T10:51:33-03:00",
  "ultimo_http_status": 500,
  "ultimo_erro": null,
  "resposta_trecho": "Internal Server Error",
  "duracao_ms": 2140,
  "entregue_em": null,
  "created_at": "2026-11-11T10:15:33-03:00"
}
Campo Descrição
id Id da entrega. É o valor do header X-Emitra-Delivery
evento_id id do evento no corpo. Igual em todas as tentativas
status pending, success, retrying ou failed
resposta_trecho Primeiro 1 KB da resposta do seu servidor

O reenvio manual de uma entrega é feito no painel. Detalhes da agenda de tentativas em Retries e boas práticas.

Testar um endpoint#

POST /integracao/webhooks/{id}/testar → 200. Envia um evento de teste assinado para a URL e devolve o resultado da tentativa.

cURL
curl -X POST https://emitra.com.br/api/v1/integracao/webhooks/b7d4e2f1-9c3a-4e8b-8f65-1a2b3c4d5e6f/testar \
  -H "Authorization: Bearer $EMITRA_API_KEY"
Resposta 200
{
  "status": "success",
  "message": "Evento de teste enviado",
  "data": { "http_status": 200, "duracao_ms": 118, "resposta_trecho": "ok" }
}

Próximos passos#

Esta página foi útil?