Listar entregas

Liste o histórico de tentativas de entrega (dispatches) dos seus webhooks: cada item registra um evento enviado a um endpoint, o resultado da tentativa e o diagnóstico HTTP do seu servidor. É a ferramenta principal para auditar entregas e investigar por que um webhook não chegou.

GET /v1/webhooks/dispatches

Como funciona

Um webhook é uma notificação HTTP que a Selectwin envia ao seu servidor quando algo acontece na sua conta (ex.: uma transação foi aprovada). Cada vez que a plataforma tenta entregar um evento a um dos seus endpoints, ela cria um dispatch (wdi_...) — o "recibo" daquela tentativa de entrega.

Este endpoint retorna esses recibos em ordem cronológica, permitindo que você responda perguntas como: o evento da transação X foi entregue? Quantas vezes tentamos? Qual código HTTP o meu servidor devolveu? Em quais endpoints estão concentradas as falhas?

Um dispatch passa por estes estados (status):

• pending — entrega criada, ainda não confirmada.
• retrying — uma tentativa falhou; a plataforma reagenda novas tentativas com backoff (espera crescente entre uma tentativa e outra).
• success — seu servidor respondeu com um código 2xx. O campo successAt é preenchido.
• failed — todas as tentativas se esgotaram sem sucesso.

O campo attempts conta quantas vezes a entrega foi tentada, e responseStatusCode/responseBody guardam o que o seu servidor devolveu na última tentativa (úteis para descobrir se o problema é um 500 seu, um 404 de rota errada ou um timeout).

Quando usar (e quando não usar)

Use esta listagem para:

• Auditar todas as entregas de um período ou de um endpoint específico.
• Diagnosticar falhas em lote (ex.: todas as entregas de um endpoint começaram a falhar com 502).
• Montar um painel operacional simples de saúde dos webhooks.

Quando não usar:

• Para métricas agregadas (taxas de sucesso/falha consolidadas) prefira Analytics, que já entrega os números resumidos.
• Para reenviar uma entrega que falhou, use Redispatch — esta página apenas lê.
• Não use esta listagem como mecanismo de polling para saber o estado dos seus pagamentos. O estado de transações/assinaturas deve ser consumido pelos próprios webhooks; veja Proibição de Polling.

Requisição

Headers

Esta é uma operação somente leitura (GET) e não envia corpo — não há Content-Type nem X-Idempotency-Key a definir.

Parâmetros de consulta (query)

Todos são opcionais. Filtros podem ser combinados (são aplicados em conjunto, com lógica E).

Para o funcionamento geral de limit/offset, hasMore e page, veja Paginação.

Exemplos curl

Consulta básica (entregas mais recentes):

curl https://api.selectwin.io/v1/webhooks/dispatches \
  -H "SelectKey: sl_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ"

Apenas entregas que falharam:

curl "https://api.selectwin.io/v1/webhooks/dispatches?onlyerrored=true" \
  -H "SelectKey: sl_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ"

Falhas de um endpoint específico:

curl -G https://api.selectwin.io/v1/webhooks/dispatches \
  -H "SelectKey: sl_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ" \
  --data-urlencode "status=failed" \
  --data-urlencode "endpoint=webhooks.mydomain.com"

Intervalo de datas (abril de 2026), 20 por página:

curl -G https://api.selectwin.io/v1/webhooks/dispatches \
  -H "SelectKey: sl_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ" \
  --data-urlencode "daterangegte=2026-04-01T00:00:00Z" \
  --data-urlencode "daterangelte=2026-04-30T23:59:59Z" \
  --data-urlencode "limit=20"

Use -G com --data-urlencode para que o curl codifique corretamente os valores (ex.: o : e a / da URL do endpoint, ou o +/Z das datas).

Resposta

Sucesso (200 OK)

A resposta é o envelope paginado padrão: dados de paginação no topo, a lista em data[], o merchant da conta e os links HATEOAS em _links.

{
  "offset": 0,
  "limit": 20,
  "total": 50,
  "hasMore": true,
  "page": {
    "current": 1,
    "total": 3,
    "offset": { "first": 0, "prev": null, "next": 20, "last": 40 }
  },
  "data": [
    {
      "id": "wdi_01hqzvabc",
      "endpoint": "https://webhooks.mydomain.com/selectwin",
      "status": "success",
      "event": "transaction.approved",
      "attempts": 1,
      "lastAttemptAt": "2026-04-12T17:56:33.000Z",
      "responseStatusCode": 200,
      "responseBody": "OK",
      "successAt": "2026-04-12T17:56:33.050Z",
      "updatedAt": "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",
      "method": "GET"
    }
  }
}

Campos do envelope

Campos de cada dispatch (data[])

Erros

Os erros seguem o envelope padrão com um error.code estável — trate sempre pelo code, não pela message. Veja Tratamento de Erros e o Catálogo de Códigos.

Boas práticas

• Filtre no servidor, não no cliente. Combine status=failed (ou onlyerrored=true) com endpoint= para isolar exatamente as entregas problemáticas, em vez de baixar tudo e filtrar localmente.
• Pagine sempre. Use limit (até 100) com offset, e siga hasMore/page até esgotar; nunca assuma que a primeira página tem todos os resultados.
• Delimite por data em auditorias com daterangegte + daterangelte (ISO 8601 UTC) para janelas previsíveis e respostas menores.
• Diagnostique pelo trio attempts + responseStatusCode + responseBody. 5xx indica erro no seu servidor; 404 sugere rota errada; ausência de responseStatusCode aponta timeout de rede.
• Para reenviar, vá ao Redispatch. Identificou um wdi_... com status: failed que deveria ter chegado? Reenvie por Redispatch em vez de esperar novas tentativas automáticas.
• Não faça polling de pagamentos por aqui. Esta listagem audita entregas, não substitui o consumo dos eventos; veja Proibição de Polling.

Veja também

• Overview — o que são webhook dispatches e o modelo do objeto.
• Analytics — métricas agregadas de entrega (taxas de sucesso/falha).
• Redispatch — reenviar uma tentativa de entrega que falhou.
• Paginação · Convenções · Autenticação