Visão Geral

Os Webhooks permitem que sua aplicação receba notificações automáticas quando eventos relacionados às suas NFes ocorrem no sistema ValidaNFe. Configure URLs de destino e filtre por chaves específicas de NFe.

Base URL

https://api.validanfe.com/Webhooks/Subscriptions

Endpoints

Listar Inscrições

Este endpoint permite obter todas as inscrições de webhooks cadastradas na sua conta, incluindo os endpoints (URLs) configurados para receber as chamadas dos webhooks.

Headers

X-API-KEY

string

required

Token de autenticação da API

Exemplos de Requisição

curl -X GET "https://api.validanfe.com/Webhooks/Subscriptions" \
  -H "Accept: application/json" \
  -H "X-API-KEY: SEU_TOKEN_AQUI"

Exemplo de Resposta

200 - Sucesso

{
  "success": true,
  "data": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "Webhook Principal",
      "url": "https://suaapp.com/webhooks/nfe",
      "isActive": true,
      "events": ["nfe.processada", "nfe.cancelada"],
      "secret": "whsec_1234567890abcdef",
      "createdAt": "2024-03-10T15:30:45Z",
      "lastDeliveryAt": "2024-03-10T16:45:30Z",
      "nfeChavesCount": 5
    }
  ]
}

Obter Inscrição

Retorna os detalhes completos de uma inscrição específica, incluindo todas as chaves NFe associadas e configurações do webhook.

Parâmetros

string

required

ID único da inscrição (UUID)

Exemplo de Resposta

200 - Sucesso

{
  "success": true,
  "data": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "name": "Webhook Principal",
    "url": "https://suaapp.com/webhooks/nfe",
    "isActive": true,
    "events": ["nfe.processada", "nfe.cancelada"],
    "secret": "whsec_1234567890abcdef",
    "createdAt": "2024-03-10T15:30:45Z",
    "lastDeliveryAt": "2024-03-10T16:45:30Z",
    "nfeChaves": [
      "35170608530528000184550000000154301000771561",
      "35170608530528000184550000000154302000771562"
    ]
  }
}

Criar Inscrição

Cria uma nova inscrição de webhook para receber notificações automáticas sobre eventos de NFe em uma URL específica.

Parâmetros do Body

name

string

required

Nome descritivo da inscrição

url

string

required

URL de destino para receber os webhooksFormato: Deve ser uma URL válida (https:// recomendado)

events

array

required

Lista de eventos para subscreverEventos disponíveis:

nfe.processada - NFe foi processada com sucesso
nfe.cancelada - NFe foi cancelada
nfe.erro - Erro no processamento da NFe

isActive

boolean

default:"true"

Se a inscrição está ativa

secret

string

Chave secreta para validação da assinaturaGerado automaticamente se não fornecido

Exemplos de Requisição

curl -X POST "https://api.validanfe.com/Webhooks/Subscriptions" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: SEU_TOKEN_AQUI" \
  -d '{
    "name": "Webhook Principal",
    "url": "https://suaapp.com/webhooks/nfe",
    "events": ["nfe.processada", "nfe.cancelada"],
    "isActive": true
  }'

Exemplo de Resposta

201 - Criado

{
  "success": true,
  "data": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "name": "Webhook Principal",
    "url": "https://suaapp.com/webhooks/nfe",
    "isActive": true,
    "events": ["nfe.processada", "nfe.cancelada"],
    "secret": "whsec_1234567890abcdef",
    "createdAt": "2024-03-10T15:30:45Z"
  }
}

Atualizar Inscrição

Atualiza as configurações de uma inscrição existente, como URL de destino, eventos ou status ativo/inativo.

Parâmetros

string

required

ID único da inscrição (UUID)

Parâmetros do Body

name

string

Nome descritivo da inscrição

url

string

URL de destino para receber os webhooks

events

array

Lista de eventos para subscrever

isActive

boolean

Se a inscrição está ativa

Exemplo de Requisição

curl -X PUT "https://api.validanfe.com/Webhooks/Subscriptions/123e4567-e89b-12d3-a456-426614174000" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: SEU_TOKEN_AQUI" \
  -d '{
    "name": "Webhook Atualizado",
    "isActive": false
  }'

Excluir Inscrição

Remove permanentemente uma inscrição de webhook. Todas as entregas pendentes para esta inscrição serão canceladas.

Parâmetros

string

required

ID único da inscrição (UUID)

Exemplo de Requisição

curl -X DELETE "https://api.validanfe.com/Webhooks/Subscriptions/123e4567-e89b-12d3-a456-426614174000" \
  -H "X-API-KEY: SEU_TOKEN_AQUI"

Gerenciar Chaves NFe

Adicionar Chave NFe

Adiciona uma chave NFe específica a uma inscrição para filtrar webhooks. Apenas eventos relacionados às chaves cadastradas serão enviados.

Parâmetros

string

required

ID único da inscrição (UUID)

Parâmetros do Body

nfeChave

string

required

Chave de acesso da NFe (44 caracteres)

Exemplo de Requisição

curl -X POST "https://api.validanfe.com/Webhooks/Subscriptions/123e4567-e89b-12d3-a456-426614174000/NFe-Chaves" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: SEU_TOKEN_AQUI" \
  -d '{
    "nfeChave": "35170608530528000184550000000154301000771561"
  }'

Remover Chave NFe

Remove uma chave NFe específica de uma inscrição. Após a remoção, eventos desta NFe não serão mais enviados para esta inscrição.

Parâmetros

string

required

ID único da inscrição (UUID)

nfeChave

string

required

Chave de acesso da NFe (44 caracteres)

Listar Chaves NFe

Retorna todas as chaves NFe associadas a uma inscrição específica. Útil para verificar quais NFes estão configuradas para receber notificações.

Exemplo de Resposta

200 - Sucesso

{
  "success": true,
  "data": [
    "35170608530528000184550000000154301000771561",
    "35170608530528000184550000000154302000771562"
  ]
}

Referência

Códigos de Resposta

200

Success

Operação realizada com sucesso

201

Created

Inscrição criada com sucesso

400

Bad Request

Dados inválidos ou malformados

401

Unauthorized

Token de autenticação ausente ou inválido

404

Not Found

Inscrição não encontrada

409

Conflict

Conflito (URL já cadastrada ou chave NFe duplicada)

429

Too Many Requests

Limite de requisições excedido

500

Internal Server Error

Erro interno do servidor

Validação de Assinatura

Todos os webhooks são enviados com uma assinatura HMAC-SHA256 no header X-Webhook-Signature:

X-Webhook-Signature: sha256=hash_calculado

Exemplo de Validação

const crypto = require('crypto');

function validateSignature(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload, 'utf8')
    .digest('hex');
  
  const receivedSignature = signature.replace('sha256=', '');
  
  return crypto.timingSafeEqual(
    Buffer.from(expectedSignature, 'hex'),
    Buffer.from(receivedSignature, 'hex')
  );
}

Estrutura do Payload

Os webhooks enviados seguem esta estrutura:

{
  "id": "delivery-uuid",
  "event": "nfe.processada",
  "timestamp": "2024-03-10T16:45:30Z",
  "data": {
    "nfeChave": "35170608530528000184550000000154301000771561",
    "status": "processada",
    "emitente": {
      "cnpj": "12345678000195",
      "razaoSocial": "Empresa Exemplo LTDA"
    },
    "valor": 1500.00,
    "dataEmissao": "2024-03-10T15:30:45Z"
  }
}

Configuração Recomendada

Configurações Ideais

URL HTTPS: Sempre use URLs com SSL
Timeout: Configure timeout de 30 segundos
Retry: Sistema faz até 3 tentativas com backoff exponencial
Resposta: Retorne status 200-299 para confirmar recebimento

Eventos Disponíveis

nfe.processada: NFe foi processada e validada com sucesso
nfe.cancelada: NFe foi cancelada oficialmente
nfe.erro: Erro durante o processamento da NFe

Próximos Passos

Webhook Deliveries

Monitore entregas e tentativas de webhook

Consultar NFe

Obtenha dados completos das NFes

Teste Seus WebhooksUse o HookDebug para testar rapidamente o recebimento de webhooks durante o desenvolvimento. Você receberá uma URL temporária que permite visualizar requisições em tempo real com detalhes completos do payload.

Precisa de Ajuda?Entre em contato: [email protected]

Começar

API NFe

API Guarda

​Visão Geral

​Base URL

​Endpoints

​Listar Inscrições

​Headers

​Exemplos de Requisição

​Exemplo de Resposta

​Obter Inscrição

​Parâmetros

​Exemplo de Resposta

​Criar Inscrição

​Parâmetros do Body

​Exemplos de Requisição

​Exemplo de Resposta

​Atualizar Inscrição

​Parâmetros

​Parâmetros do Body

​Exemplo de Requisição

​Excluir Inscrição

​Parâmetros

​Exemplo de Requisição

​Gerenciar Chaves NFe

​Adicionar Chave NFe

​Parâmetros

​Parâmetros do Body

​Exemplo de Requisição

​Remover Chave NFe

​Parâmetros

​Listar Chaves NFe

​Exemplo de Resposta

​Referência

​Códigos de Resposta

​Validação de Assinatura

​Exemplo de Validação

​Estrutura do Payload

​Configuração Recomendada

​Próximos Passos

Webhook Deliveries

Consultar NFe

Visão Geral

Base URL

Endpoints

Listar Inscrições

Headers

Exemplos de Requisição

Exemplo de Resposta

Obter Inscrição

Parâmetros

Exemplo de Resposta

Criar Inscrição

Parâmetros do Body

Exemplos de Requisição

Exemplo de Resposta

Atualizar Inscrição

Parâmetros

Parâmetros do Body

Exemplo de Requisição

Excluir Inscrição

Parâmetros

Exemplo de Requisição

Gerenciar Chaves NFe

Adicionar Chave NFe

Parâmetros

Parâmetros do Body

Exemplo de Requisição

Remover Chave NFe

Parâmetros

Listar Chaves NFe

Exemplo de Resposta

Referência

Códigos de Resposta

Validação de Assinatura

Exemplo de Validação

Estrutura do Payload

Configuração Recomendada

Próximos Passos