Métricas e análises

Recupere as tentativas de entrega (dispatches) de webhook criadas dentro de um período para medir a saúde da sua integração — taxa de sucesso, falhas e quantas retentativas foram necessárias. É uma operação somente de leitura: você informa um intervalo de datas e recebe as linhas individuais de cada tentativa, prontas para alimentar gráficos e painéis de monitoramento.

GET /v1/webhooks/dispatches/analytics

Como funciona

Um dispatch é o registro de uma tentativa de entregar um evento (por exemplo transaction.approved) à URL do seu endpoint de webhook. Cada vez que a Selectwin tenta enviar um evento, ela cria/atualiza um dispatch com o resultado: se o seu servidor respondeu, qual código HTTP retornou, quantas tentativas foram feitas e quando.

Este endpoint devolve uma projeção enxuta desses dispatches dentro da janela initdate–enddate: apenas os campos úteis para análise (id, status, attempts, responseStatusCode, lastAttemptAt, createdAt). Ele não agrega os dados por você — não calcula "85% de sucesso" nem agrupa por dia. Você recebe as linhas e faz a agregação no seu lado (somando, agrupando por dia, calculando taxas). Pense nele como a fonte de dados crua para o seu dashboard.

O filtro de período incide sobre o createdAt do dispatch — ou seja, você vê as tentativas criadas no intervalo, não as que mudaram de status nele.

Ciclo de vida de um dispatch

O campo status percorre estes estados, e é ele que você vai contabilizar:

Quando usar

• Monitoramento e alertas: alimentar um gráfico de "taxa de entrega ao longo do tempo" e disparar alertas quando ela cair.
• Diagnóstico de incidentes: depois de uma indisponibilidade do seu servidor, medir quantas entregas falharam no período.
• Relatórios periódicos: consolidar a confiabilidade da integração por dia/semana/mês.

Quando NÃO usar: se você quer inspecionar uma entrega específica (corpo da resposta, endpoint exato, evento), use a listagem, que traz campos completos (endpoint, event, responseBody, successAt). E lembre: webhooks já são push — não use este endpoint para fazer polling em busca de novos eventos. Veja Proibição de polling.

Requisição

Headers

Por ser uma leitura sem corpo, não há Content-Type nem X-Idempotency-Key. Detalhes em Autenticação.

Parâmetros de consulta

Ambos os parâmetros são obrigatórios e usam datas em ISO 8601 UTC.

Exemplo

curl -G "https://api.selectwin.io/v1/webhooks/dispatches/analytics" \
  -H "SelectKey: sl_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ" \
  --data-urlencode "initdate=2026-01-01T00:00:00Z" \
  --data-urlencode "enddate=2026-01-31T23:59:59Z"

Resposta

200 OK

{
  "analytics": [
    {
      "id": "wdi_01hqzvabc",
      "status": "success",
      "attempts": 1,
      "responseStatusCode": 200,
      "lastAttemptAt": "2026-04-12T17:56:33.000Z",
      "createdAt": "2026-04-12T17:56:33.000Z"
    }
  ],
  "merchant": {
    "name": "Seller Name",
    "merchantId": "bus_1234567890",
    "isSubAccount": false
  },
  "_links": {
    "self": {
      "href": "https://api.selectwin.io/v1/webhooks/dispatches/analytics",
      "method": "GET",
      "description": "View analytics for webhook dispatches."
    },
    "list": {
      "href": "https://api.selectwin.io/v1/webhooks/dispatches",
      "method": "GET",
      "description": "List all webhook dispatches."
    }
  }
}

Campos da resposta

Cada item de analytics

Erros

Veja o catálogo completo em Códigos de erro e o formato do envelope em Convenções. O código webhookDispatchIdInvalid aplica-se ao redespacho por dispatchId, não a este endpoint.

Boas práticas

1. Agregue do seu lado para obter a taxa de sucesso. Agrupe as linhas por dia e calcule success ÷ total (ou conte failed) — a API entrega linhas cruas, não percentuais.
2. Use janelas curtas e fixas. Períodos longos retornam muitas linhas; consulte por dia ou por hora para dashboards e mantenha as datas alinhadas ao seu fuso convertido para UTC.
3. Vigie responseStatusCode. Concentração de 5xx indica seu servidor fora do ar; 4xx costuma ser erro de configuração (autenticação ou rota incorreta no seu receptor).
4. Acompanhe attempts. Médias acima de 1 mostram que muitas entregas só passam após retentativa — sinal de instabilidade ou lentidão do seu endpoint.
5. Da métrica para a causa raiz. Detectou queda no gráfico? Vá para a listagem com onlyerrored=true e status=failed no mesmo período para inspecionar responseBody e endpoint das falhas.
6. Não use para descobrir novos eventos. Para receber eventos em tempo real, configure um endpoint de webhook; este recurso é para análise histórica, não para polling.

Veja também

• Visão geral de Webhook Dispatches — o que é um dispatch e seu ciclo de vida.
• Listar dispatches — entregas com campos completos e filtros avançados.
• Redespachar uma entrega — reenviar manualmente um dispatch que falhou.
• Proibição de polling — por que webhooks substituem o polling.
• Autenticação e Convenções.