Analisar endpoints

Recupere as tentativas de entrega mais recentes de um endpoint de webhook para diagnosticar a saúde da sua integração: quais disparos chegaram ao seu servidor, quais falharam e quando foi a última tentativa. É uma operação somente de leitura, ideal para monitorar confiabilidade e investigar problemas de conectividade.

GET /v1/webhooks/endpoints/{endpointId}/analytics

Como funciona

Um webhook é uma notificação HTTP que a Selectwin envia ao seu servidor quando algo acontece (por exemplo, uma transação aprovada). Cada notificação enviada a um endpoint é um disparo (dispatch). Este endpoint devolve as linhas mais recentes desses disparos — pense nelas como o histórico de entregas do endpoint.

Para cada linha, a API informa se a entrega foi bem-sucedida (delivered) e o horário da última tentativa (lastAttempt). Uma entrega é considerada bem-sucedida quando o seu servidor responde com um status HTTP 2xx dentro do tempo limite; caso contrário, delivered é false. Cada linha tem o seu próprio id no formato wbh_… (identificador de evento de webhook), distinto do id wbe_… do endpoint que você está consultando.

Pontos importantes sobre o comportamento:

• Somente leitura. Consultar a análise não altera, reativa nem reenvia nada — não afeta a configuração do endpoint.
• Visão histórica, não tempo real. Os dados refletem disparos já registrados; um disparo em andamento pode ainda não aparecer.
• Ordenável. Use o parâmetro de query sort para trazer as linhas mais novas ou mais antigas primeiro.
• Atualizações são push, não pull. Esta análise serve para monitorar a entrega; ela não substitui o recebimento dos eventos. Não fique consultando-a em laço para "buscar" eventos — veja Proibição de Polling.

Quando usar

• Para construir um painel de saúde dos seus webhooks (taxa de sucesso por endpoint).
• Ao investigar por que eventos não estão chegando: verifique se há linhas com delivered: false e quando foi lastAttempt.
• Após mudar a URL, a infraestrutura ou as regras de firewall do seu receptor, para confirmar que as entregas voltaram a ter sucesso.

Quando não usar: se você precisa apenas dos metadados de configuração do endpoint (nome, URL, eventos inscritos, shotsQty, failedShotsQty), use Ler (GET /v1/webhooks/endpoints/{endpointId}) ou Listar — eles já trazem contadores agregados sem precisar percorrer linhas individuais.

Requisição

Headers

Por ser um GET sem corpo, não há Content-Type nem X-Idempotency-Key.

Parâmetro de caminho

Parâmetros de query

Exemplo curl

curl https://api.selectwin.io/v1/webhooks/endpoints/wbe_01hqzvabc/analytics?sort=descending \
  -H "SelectKey: sl_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ"

Resposta

Sucesso (200 OK)

{
  "analytics": [
    {
      "id": "wbh_01hqzvabc",
      "delivered": true,
      "lastAttempt": "2026-04-12T17:56:33.000Z",
      "updatedAt": "2026-04-12T17:56:33.000Z",
      "createdAt": "2026-04-12T17:56:32.000Z"
    },
    {
      "id": "wbh_01hqzvdef",
      "delivered": false,
      "lastAttempt": "2026-04-12T16:10:00.000Z",
      "updatedAt": "2026-04-12T16:10:05.000Z",
      "createdAt": "2026-04-12T16:10:00.000Z"
    }
  ],
  "merchant": {
    "name": "Seller Name",
    "merchantId": "bus_1234567890",
    "isSubAccount": false
  },
  "_links": {
    "self": {
      "href": "https://api.selectwin.io/v1/webhooks/endpoints/wbe_01hqzvabc/analytics",
      "method": "GET",
      "description": "View analytics for the webhook."
    },
    "read": {
      "href": "https://api.selectwin.io/v1/webhooks/endpoints/wbe_01hqzvabc",
      "method": "GET",
      "description": "Read a webhook endpoint."
    },
    "update": {
      "href": "https://api.selectwin.io/v1/webhooks/endpoints/wbe_01hqzvabc",
      "method": "PUT",
      "description": "Update the webhook endpoint."
    },
    "delete": {
      "href": "https://api.selectwin.io/v1/webhooks/endpoints/wbe_01hqzvabc",
      "method": "DELETE",
      "description": "Delete the webhook endpoint."
    },
    "create": {
      "href": "https://api.selectwin.io/v1/webhooks/endpoints",
      "method": "POST",
      "description": "Create a new webhook endpoint."
    },
    "list": {
      "href": "https://api.selectwin.io/v1/webhooks/endpoints",
      "method": "GET",
      "description": "List all webhook endpoints."
    }
  }
}

Campos da resposta

Erros

A resposta de erro segue o envelope padrão com error.code estável — trate sempre pelo code, nunca pela message. Veja Tratamento de Erros e o Catálogo de Códigos de Erro.

Exemplo de endpointId malformado (400):

{
  "error": {
    "code": "invalidParameters",
    "statusCode": 400,
    "category": "validation",
    "message": "Validation errors occurred.",
    "params": [
      { "endpointId": "Formato esperado: wbe_XXXXXXXXX" }
    ]
  }
}

Em validações específicas de Webhooks, o code deste 400 pode vir como invalidWebhookEndpointId. Por isso, decida o tratamento pelo statusCode (400)/category (validation), não por um code específico.

Exemplo de endpoint inexistente (404):

{
  "error": {
    "code": "notFound",
    "statusCode": 404,
    "category": "client",
    "message": "Webhook endpoint not found."
  }
}

Boas práticas

1. Monitore a proporção de delivered: false ao longo das linhas para detectar degradação de entrega antes que vire incidente.
2. Combine análise + contadores. Use failedShotsQty/shotsQty de Ler para a taxa geral e este endpoint para inspecionar quais disparos falharam e quando (lastAttempt).
3. Trate error.code, não message. A message é texto e pode mudar; o code faz parte do contrato.
4. Não use a análise como fila de eventos. Ela é diagnóstico de entrega; receber os eventos é responsabilidade do seu endpoint HTTP. Evite consultá-la em laço — veja Proibição de Polling.
5. Ordene com sort=descending para revisar primeiro as tentativas mais recentes ao investigar um problema ativo.
6. Garanta resposta 2xx rápida no seu receptor: responda primeiro e processe depois, de forma assíncrona, para que disparos lentos não virem falhas por timeout.
7. Reverifique após mudanças. Depois de alterar a URL (Atualizar) ou a infraestrutura do receptor, consulte a análise para confirmar que as novas tentativas retornam delivered: true.

Veja também

• Visão geral dos Webhook Endpoints — modelo do objeto e ciclo de vida.
• Listar endpoints — contadores agregados (shotsQty, failedShotsQty) por endpoint.
• Atualizar endpoint — corrigir URL, eventos ou cabeçalhos de autorização.
• Excluir endpoint — remover um endpoint que não deve mais receber notificações.
• Verificando Assinaturas de Webhook — valide a autenticidade dos disparos recebidos.
• Convenções da API — datas ISO 8601 UTC, IDs opacos, camelCase.