Listar endpoints

Recupera, de forma paginada, todos os webhook endpoints (URLs cadastradas para receber notificações de eventos) da sua conta. Use esta operação para auditar suas integrações, descobrir o id de cada endpoint antes de atualizar, ler ou apagar, e monitorar saúde de entrega pelos contadores de disparos.

GET /v1/webhooks/endpoints

Um webhook endpoint é uma URL HTTPS sua para a qual a Selectwin envia, em tempo real, um POST sempre que ocorre um evento que você assinou (por exemplo transaction.approved). Listar endpoints é como abrir o "painel" de todas essas URLs de uma vez.

Como funciona

Esta é a operação de leitura em lote do recurso. O servidor devolve uma página de endpoints (não a lista inteira de uma vez) usando o padrão de paginação por offset/limit comum a toda a API. A resposta traz, no nível raiz, os metadados de paginação (offset, limit, total, hasMore, page), o array data com os endpoints, o objeto merchant e os _links HATEOAS para navegação.

Pontos importantes do mecanismo:

• Projeção leve. Cada item de data[] é uma versão resumida do endpoint. Campos sensíveis e detalhados — como authorization (cabeçalho de autenticação) e metadata — não aparecem aqui. Para o objeto completo, consulte Read (GET /v1/webhooks/endpoints/{endpointId}). O secret (segredo de assinatura) não vem em nenhuma listagem nem leitura: ele aparece apenas na resposta de Create.
• Somente leitura. A operação não altera nada e não consome chave de idempotência; pode ser repetida à vontade (respeitando o limite de requisições).
• Contadores de entrega. Os campos shotsQty (total de disparos) e failedShotsQty (disparos que falharam) ajudam a identificar endpoints com problemas sem precisar abrir cada um. Para o histórico detalhado de entregas, use Analyze.
• Ordenação e filtros são aplicados no servidor via parâmetros de query (abaixo), antes da paginação.

Para entender o envelope de paginação em detalhe, veja Paginação.

Quando usar

• Para descobrir o id (wbe_...) de um endpoint antes de chamar Read, Update, Delete ou Analyze.
• Para auditar quais URLs estão cadastradas, quais eventos cada uma assina e se estão habilitadas (enabled).
• Para monitorar saúde comparando shotsQty com failedShotsQty e olhando o lastEventSent de cada endpoint.

Quando não usar:

• Para receber atualizações de estado em tempo real (transação aprovada, etc.). Isso é função do próprio webhook chegando à sua URL — não fique consultando esta lista em loop. Veja Proibição de Polling.
• Para obter authorization ou metadata de um endpoint específico: use Read, pois esses campos não vêm na listagem. (O secret não vem em nenhuma das duas — só na criação.)

Requisição

Headers

Esta operação é uma leitura sem corpo, então não envie Content-Type nem X-Idempotency-Key.

Parâmetros de query

Todos são opcionais. Combine paginação, ordenação e filtros livremente.

As datas dos parâmetros daterange* seguem o padrão da API: ISO 8601 em UTC (sufixo Z). Para paginar grandes intervalos, prefira combinar daterangegte + daterangelt com limit/offset.

Exemplo de requisição

curl -G https://api.selectwin.io/v1/webhooks/endpoints \
  -H "SelectKey: sl_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ" \
  --data-urlencode "limit=20" \
  --data-urlencode "offset=0" \
  --data-urlencode "sort=descending" \
  --data-urlencode "status=active"

Resposta

200 OK. O corpo é o objeto paginado diretamente (sem invólucro extra).

{
  "offset": 0,
  "limit": 20,
  "total": 2,
  "hasMore": false,
  "page": {
    "current": 1,
    "total": 1,
    "offset": { "first": 0, "prev": null, "next": null, "last": 0 }
  },
  "data": [
    {
      "id": "wbe_01hqzvabc",
      "name": "Webhook MyDomain",
      "endpoint": "https://webhooks.mydomain.com/selectwin",
      "enabled": true,
      "events": ["transaction.approved", "transaction.pending"],
      "shotsQty": 3068,
      "failedShotsQty": 12,
      "lastEventSent": "2026-04-12T17:56:33.000Z",
      "updatedAt": "2026-04-12T17:56:33.000Z",
      "createdAt": "2025-01-26T20:18:05.000Z"
    }
  ],
  "merchant": {
    "name": "Seller Name",
    "merchantId": "bus_1234567890",
    "isSubAccount": false
  },
  "_links": {
    "self": {
      "href": "https://api.selectwin.io/v1/webhooks/endpoints",
      "method": "GET",
      "description": "List all webhook endpoints."
    }
  }
}

Campos da resposta

Metadados de paginação (nível raiz)

Item de data[] (projeção do endpoint)

Erros

Trate sempre pelo error.code estável, nunca pela message. Veja o Catálogo de Códigos de Erro e a estrutura do envelope de erro.

Exemplo de 400 por paginação inválida:

{
  "error": {
    "code": "invalidParameters",
    "statusCode": 400,
    "category": "validation",
    "message": "Validation errors occurred.",
    "params": [
      { "limit": "O valor de 'limit' deve ser um número inteiro entre 1 e 100" },
      { "offset": "O valor de 'offset' deve ser um número inteiro não negativo" }
    ]
  }
}

Boas práticas

1. Pagine sempre. Não assuma que tudo cabe numa página: itere usando page.offset.next (ou offset += limit) enquanto hasMore for true.
2. Filtre no servidor. Use name, endpoint e status para reduzir o tráfego em vez de baixar tudo e filtrar no cliente.
3. Monitore saúde com failedShotsQty. Um endpoint com failedShotsQty alto em relação a shotsQty provavelmente está fora do ar ou rejeitando entregas — investigue com Analyze.
4. Acompanhe lastEventSent. Um endpoint enabled: true sem eventos recentes pode indicar que ele não assina nenhum evento que está de fato acontecendo, ou que algo no roteamento mudou.
5. Guarde o id, trate-o como opaco. Use o wbe_... para as operações seguintes; não tente interpretar seu conteúdo (veja Convenções).
6. Não use a lista como polling de estado. Para saber que uma transação foi aprovada, receba o webhook — não fique listando endpoints. Veja Proibição de Polling.
7. Use daterange* para auditorias por período (ex.: endpoints criados num intervalo), sempre em ISO 8601 UTC.

Veja também

• Visão Geral de Webhook Endpoints — modelo do objeto e ciclo de vida.
• Create — cadastrar um novo endpoint.
• Read — obter um endpoint completo (com authorization/metadata).
• Update — alterar URL, eventos ou cabeçalhos.
• Delete — remover um endpoint.
• Analyze — estatísticas de entrega de um endpoint.
• Paginação · Convenções · Autenticação · Catálogo de Códigos de Erro