Configuração e Gerenciamento de Webhooks

Cadastrar endpoints, filtrar eventos, atualizar URLs e rotacionar chaves secretas.

Você pode cadastrar e gerenciar endpoints de webhook diretamente pelo Dashboard da NFER ou programaticamente via API REST. Cada endpoint é vinculado a uma empresa ou organização e recebe uma chave secreta exclusiva (whsec_...) para validação de assinaturas digitais.

1. Endpoints de Gerenciamento

POST/v1/webhooks

Cadastra uma nova URL HTTPS para recebimento de eventos fiscais.

GET/v1/webhooks

Lista todos os endpoints de webhook cadastrados para a empresa.

GET/v1/webhooks/events

Lista todos os tipos de eventos suportados pelo sistema de webhooks.

PUT/v1/webhooks/:id

Atualiza a URL de destino, status ativo/inativo (active) ou lista de eventos.

DELETE/v1/webhooks/:id

Remove definitivamente o endpoint de webhook.

POST/v1/webhooks/:id/rotate-secret

Gera uma nova chave secreta HMAC para o webhook.

POST/v1/webhooks/:id/test-connection

Dispara um evento de teste de conectividade HTTP para validação do endpoint.

2. Cadastrando um Endpoint via cURL

Para criar um novo endpoint, informe a URL pública HTTPS e a lista de eventos desejados. Se você omitir events, o webhook será inscrito em todos os eventos suportados:

curl -X POST "https://api.nfer.me/v1/webhooks" \

-H "Authorization: Bearer sec_live_sua_chave_secreta" \

-H "Content-Type: application/json" \

-d '{

"url": "https://api.seusistema.com.br/webhooks/nfer",

"description": "Servidor de Faturamento Principal",

"events": [

"nfe.autorizada",

"nfe.erro",

"nfe.cancelada",

"nfe.denegada"

]

Resposta de sucesso retornando o identificador e a chave secreta gerada:

{

"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",

"url": "https://api.seusistema.com.br/webhooks/nfer",

"active": true,

"events": [

"nfe.autorizada",

"nfe.erro",

"nfe.cancelada",

"nfe.denegada"

"description": "Servidor de Faturamento Principal",

"signed": true,

Guarde o Segredo com Segurança

O campo secret só é retornado de forma visível na criação ou quando você rotaciona o segredo. Armazene-o nas variáveis de ambiente do seu servidor (NFER_WEBHOOK_SECRET) para validar os payloads recebidos.

3. Rotação de Segredo sem Downtime

Se houver suspeita de vazamento de credenciais ou para cumprir políticas corporativas periódicas de segurança, utilize o endpoint de rotação:

curl -X POST "https://api.nfer.me/v1/webhooks/3fa85f64-5717-4562-b3fc-2c963f66afa6/rotate-secret" \

-H "Authorization: Bearer sec_live_sua_chave_secreta"

A NFER mantém um período de carência (dual-signature) de 24 horas onde você pode validar tanto com a chave anterior quanto com a nova, permitindo atualizar o deploy dos seus servidores sem descartar entregas legítimas.