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/:id

Retorna os detalhes de um webhook específico (status, eventos inscritos e histórico).

PUT/v1/webhooks/:id

Atualiza a URL de destino, status ativo/inativo ou lista de eventos inscritos.

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 com período de transição.

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ê enviar "*", o webhook receberá todos os eventos gerados pela sua empresa:

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.authorized",

"nfe.rejected",

"nfe.canceled",

"company.certificate_expiring"

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

{

"id": "whk_01HXYZ7890ABCDEF",

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

"description": "Servidor de Faturamento Principal",

"status": "active",

"events": [

"nfe.authorized",

"nfe.rejected",

"nfe.canceled",

"company.certificate_expiring"

"secret": "whsec_live_9a8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d",

Guarde o Segredo com Segurança

O campo secret só é retornado de forma visível uma única vez 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/whk_01HXYZ7890ABCDEF/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.