Webhook Deliveries

Visão Geral

A API de Webhook Deliveries permite monitorar todas as entregas de webhooks, incluindo tentativas bem-sucedidas, falhas, e opções para reenvio. Essencial para debug e monitoramento de integrações.

Base URL

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

Listar Entregas por Inscrição

Retorna todas as entregas de webhook de uma inscrição específica, com filtros por status, data e paginação para facilitar o monitoramento.

Parâmetros

subscriptionId

string

required

ID da inscrição de webhook (UUID)

Query Parameters

status

string

Filtrar por status de entregaValores: pending, success, failed, cancelled

from

string

Data inicial para filtro (ISO 8601)Exemplo: 2024-03-01T00:00:00Z

string

Data final para filtro (ISO 8601)Exemplo: 2024-03-31T23:59:59Z

page

number

default:"1"

Número da página

pageSize

number

default:"20"

Itens por página (máximo 100)

Headers

X-API-KEY

string

required

Token de autenticação da API

Exemplos de Requisição

curl -X GET "https://api.validanfe.com/Webhooks/Deliveries/Subscription/123e4567-e89b-12d3-a456-426614174000?status=failed&page=1&pageSize=20" \
  -H "Accept: application/json" \
  -H "X-API-KEY: SEU_TOKEN_AQUI"

Exemplo de Resposta

200 - Sucesso

{
  "success": true,
  "data": {
    "items": [
      {
        "id": "delivery-uuid-1",
        "subscriptionId": "123e4567-e89b-12d3-a456-426614174000",
        "event": "nfe.processada",
        "status": "failed",
        "nfeChave": "35170608530528000184550000000154301000771561",
        "url": "https://suaapp.com/webhooks/nfe",
        "attemptCount": 3,
        "lastAttemptAt": "2024-03-10T16:45:30Z",
        "nextRetryAt": "2024-03-10T17:15:30Z",
        "createdAt": "2024-03-10T16:30:00Z",
        "lastError": "Connection timeout after 30 seconds"
      }
    ],
    "pagination": {
      "page": 1,
      "pageSize": 20,
      "totalItems": 156,
      "totalPages": 8
    }
  }
}

Obter Detalhes da Entrega

Retorna informações completas de uma entrega específica, incluindo payload enviado, tentativas realizadas e detalhes de erros.

Parâmetros

deliveryId

string

required

ID único da entrega (UUID)

Exemplo de Resposta

200 - Sucesso

{
  "success": true,
  "data": {
    "id": "delivery-uuid-1",
    "subscriptionId": "123e4567-e89b-12d3-a456-426614174000",
    "subscriptionName": "Webhook Principal",
    "event": "nfe.processada",
    "status": "success",
    "nfeChave": "35170608530528000184550000000154301000771561",
    "url": "https://suaapp.com/webhooks/nfe",
    "payload": {
      "id": "delivery-uuid-1",
      "event": "nfe.processada",
      "timestamp": "2024-03-10T16:45:30Z",
      "data": {
        "nfeChave": "35170608530528000184550000000154301000771561",
        "status": "processada",
        "emitente": {
          "cnpj": "12345678000195",
          "razaoSocial": "Empresa Exemplo LTDA"
        },
        "valor": 1500.00
      }
    },
    "attemptCount": 1,
    "lastAttemptAt": "2024-03-10T16:45:30Z",
    "createdAt": "2024-03-10T16:30:00Z",
    "completedAt": "2024-03-10T16:45:30Z"
  }
}

Entregas por NFe

Lista todas as entregas de webhook relacionadas a uma NFe específica, mostrando quais inscrições receberam notificações.

Parâmetros

nfeChave

string

required

Chave de acesso da NFe (44 caracteres)

Exemplo de Resposta

200 - Sucesso

{
  "success": true,
  "data": [
    {
      "id": "delivery-uuid-1",
      "subscriptionId": "123e4567-e89b-12d3-a456-426614174000",
      "subscriptionName": "Webhook Principal",
      "event": "nfe.processada",
      "status": "success",
      "attemptCount": 1,
      "createdAt": "2024-03-10T16:30:00Z",
      "completedAt": "2024-03-10T16:45:30Z"
    },
    {
      "id": "delivery-uuid-2",
      "subscriptionId": "456e7890-e89b-12d3-a456-426614174001",
      "subscriptionName": "Webhook Backup",
      "event": "nfe.processada",
      "status": "failed",
      "attemptCount": 3,
      "createdAt": "2024-03-10T16:30:00Z",
      "lastError": "HTTP 500: Internal Server Error"
    }
  ]
}

Tentar Novamente

Força uma nova tentativa de entrega para um webhook que falhou, permitindo configurar prioridade e atraso da tentativa.

Parâmetros

deliveryId

string

required

ID único da entrega (UUID)

Parâmetros do Body

priority

string

default:"normal"

Prioridade da nova tentativaValores: low, normal, high

delay

number

default:"0"

Atraso em segundos antes da tentativaMáximo: 3600 (1 hora)

Exemplos de Requisição

curl -X POST "https://api.validanfe.com/Webhooks/Deliveries/delivery-uuid-1/Retry" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: SEU_TOKEN_AQUI" \
  -d '{
    "priority": "high",
    "delay": 60
  }'

Exemplo de Resposta

200 - Sucesso

{
  "success": true,
  "data": {
    "message": "Entrega agendada para nova tentativa",
    "deliveryId": "delivery-uuid-1",
    "scheduledFor": "2024-03-10T17:16:30Z",
    "priority": "high"
  }
}

Cancelar Entrega

Cancela uma entrega pendente que ainda não foi processada, impedindo futuras tentativas de envio.

Parâmetros

deliveryId

string

required

ID único da entrega (UUID)

Exemplo de Resposta

200 - Sucesso

{
  "success": true,
  "data": {
    "message": "Entrega cancelada com sucesso",
    "deliveryId": "delivery-uuid-1",
    "cancelledAt": "2024-03-10T17:00:00Z"
  }
}

Tentativas de Entrega

Listar Todas as Tentativas

Retorna o histórico completo de todas as tentativas de entrega, incluindo códigos de resposta e tempos de execução.

Obter Última Tentativa

Retorna apenas os detalhes da tentativa mais recente de entrega, útil para diagnóstico rápido.

Exemplo de Resposta (Tentativas)

200 - Sucesso

{
  "success": true,
  "data": [
    {
      "attemptNumber": 1,
      "timestamp": "2024-03-10T16:30:00Z",
      "responseStatus": 500,
      "responseBody": "Internal Server Error",
      "responseHeaders": {
        "Content-Type": "text/plain",
        "Server": "nginx/1.20.1"
      },
      "duration": 5234,
      "error": "HTTP 500: Internal Server Error"
    },
    {
      "attemptNumber": 2,
      "timestamp": "2024-03-10T16:35:00Z",
      "responseStatus": 200,
      "responseBody": "OK",
      "duration": 1234,
      "success": true
    }
  ]
}

Operações em Lote

Tentar Novamente Todas as Falhas

Reprocessa em lote todas as entregas que falharam para uma inscrição específica, útil para recuperação após problemas no servidor de destino.

Exemplo de Resposta

200 - Sucesso

{
  "success": true,
  "data": {
    "message": "Tentativas agendadas com sucesso",
    "subscriptionId": "123e4567-e89b-12d3-a456-426614174000",
    "retriesScheduled": 15,
    "estimatedCompletionTime": "2024-03-10T17:30:00Z"
  }
}

Estatísticas

Fornece métricas detalhadas sobre entregas de webhook, incluindo taxas de sucesso, tempos médios e distribuição de erros.

Query Parameters

subscriptionId

string

Filtrar por inscrição específica (UUID)

from

string

Data inicial para estatísticas (ISO 8601)

string

Data final para estatísticas (ISO 8601)

Exemplo de Resposta

200 - Sucesso

{
  "success": true,
  "data": {
    "period": {
      "from": "2024-03-01T00:00:00Z",
      "to": "2024-03-31T23:59:59Z"
    },
    "totalDeliveries": 1250,
    "successfulDeliveries": 1180,
    "failedDeliveries": 70,
    "successRate": 94.4,
    "averageDeliveryTime": 1834,
    "deliveriesByStatus": {
      "success": 1180,
      "failed": 70,
      "pending": 0,
      "cancelled": 0
    },
    "deliveriesByEvent": {
      "nfe.processada": 1100,
      "nfe.cancelada": 150
    },
    "errorBreakdown": {
      "timeout": 45,
      "http_5xx": 20,
      "connection_refused": 5
    }
  }
}

Endpoints Administrativos

Acesso RestritoOs endpoints abaixo requerem privilégios de administrador e não estão disponíveis para usuários regulares.

Status de Saúde

Verifica a saúde geral do sistema de entregas de webhook, retornando métricas de performance e disponibilidade.

Contar Entregas Pendentes

Retorna o número total de entregas aguardando processamento em todas as inscrições.

Listar Entregas Falhadas

Retorna todas as entregas que falharam após esgotar as tentativas automáticas, com detalhes dos erros.

Listar Prontas para Retry

Retorna entregas que estão prontas para uma nova tentativa após o período de espera do backoff.

Arquivar Entregas Antigas

Move entregas antigas para arquivo, mantendo apenas registros recentes ativos para melhor performance.

Limpar Entregas Antigas

Remove permanentemente entregas muito antigas do sistema para liberar espaço de armazenamento.

Códigos de Resposta

200

Success

Operação realizada com sucesso

400

Bad Request

Parâmetros inválidos ou malformados

401

Unauthorized

Token de autenticação ausente ou inválido

403

Forbidden

Acesso negado (endpoints administrativos)

404

Not Found

Entrega, inscrição ou NFe não encontrada

409

Conflict

Operação conflitante (ex: tentar cancelar entrega já concluída)

429

Too Many Requests

Limite de requisições excedido

500

Internal Server Error

Erro interno do servidor

Status de Entrega

Estados Possíveis

pending: Entrega aguardando processamento
processing: Entrega em andamento
success: Entrega realizada com sucesso
failed: Entrega falhou após todas as tentativas
cancelled: Entrega cancelada manualmente

Política de Retry

Tentativas: Até 3 tentativas automáticas
Intervalo: Backoff exponencial (1min, 5min, 30min)
Timeout: 30 segundos por tentativa
Success: Status HTTP 200-299
Retry manual: Sempre disponível para falhas

Códigos de Erro Comuns

timeout: Timeout de conexão (30s)
connection_refused: Servidor recusou conexão
http_4xx: Erro do cliente (URL inválida, etc.)
http_5xx: Erro do servidor de destino
dns_error: Erro de resolução DNS
ssl_error: Erro de certificado SSL

Monitoramento Recomendado

Alertas ImportantesConfigure alertas para:

Taxa de falha > 5%
Entregas pendentes > 100
Tempo médio de entrega > 10s
Entregas sem tentativa há mais de 1 hora

Próximos Passos

Webhook Subscriptions

Configure e gerencie suas inscrições

NFe Completa

Consulte dados detalhados das NFes

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

Começar

API NFe

API Guarda

​Visão Geral

​Base URL

​Listar Entregas por Inscrição

​Parâmetros

​Query Parameters

​Headers

​Exemplos de Requisição

​Exemplo de Resposta

​Obter Detalhes da Entrega

​Parâmetros

​Exemplo de Resposta

​Entregas por NFe

​Parâmetros

​Exemplo de Resposta

​Tentar Novamente

​Parâmetros

​Parâmetros do Body

​Exemplos de Requisição

​Exemplo de Resposta

​Cancelar Entrega

​Parâmetros

​Exemplo de Resposta

​Tentativas de Entrega

​Listar Todas as Tentativas

​Obter Última Tentativa

​Exemplo de Resposta (Tentativas)

​Operações em Lote

​Tentar Novamente Todas as Falhas

​Exemplo de Resposta

​Estatísticas

​Query Parameters

​Exemplo de Resposta

​Endpoints Administrativos

​Status de Saúde

​Contar Entregas Pendentes

​Listar Entregas Falhadas

​Listar Prontas para Retry

​Arquivar Entregas Antigas

​Limpar Entregas Antigas

​Códigos de Resposta

​Status de Entrega

​Monitoramento Recomendado

​Próximos Passos

Webhook Subscriptions

NFe Completa

Visão Geral

Base URL

Listar Entregas por Inscrição

Parâmetros

Query Parameters

Headers

Exemplos de Requisição

Exemplo de Resposta

Obter Detalhes da Entrega

Parâmetros

Exemplo de Resposta

Entregas por NFe

Parâmetros

Exemplo de Resposta

Tentar Novamente

Parâmetros

Parâmetros do Body

Exemplos de Requisição

Exemplo de Resposta

Cancelar Entrega

Parâmetros

Exemplo de Resposta

Tentativas de Entrega

Listar Todas as Tentativas

Obter Última Tentativa

Exemplo de Resposta (Tentativas)

Operações em Lote

Tentar Novamente Todas as Falhas

Exemplo de Resposta

Estatísticas

Query Parameters

Exemplo de Resposta

Endpoints Administrativos

Status de Saúde

Contar Entregas Pendentes

Listar Entregas Falhadas

Listar Prontas para Retry

Arquivar Entregas Antigas

Limpar Entregas Antigas

Códigos de Resposta

Status de Entrega

Monitoramento Recomendado

Próximos Passos