Listar eventos

Liste o histórico de eventos de webhook da sua conta — as notificações que a Selectwin gerou (ex.: transaction.approved) junto com o registro de cada tentativa de entrega aos seus endpoints. Use esta listagem para auditar o que aconteceu, diagnosticar entregas que falharam e localizar o evento que você quer reenviar.

GET /v1/webhooks/events

Como funciona

Um evento de webhook é o registro de algo que aconteceu na sua conta (uma transação foi aprovada, um saque mudou de estado, etc.). Cada evento tem um type (ex.: transaction.approved), aponta para o recurso de origem (resource + requestPayload) e guarda o histórico de despachos (dispatches[]) — uma tentativa de entrega por endpoint configurado.

Entender a diferença entre os dois objetos é a chave para usar esta página:

• Evento (wbh_…): a notificação em si. Existe uma vez, independentemente de quantos endpoints você tem. Tem um status agregado de entrega.
• Despacho (wdi_…): a tentativa de entregar aquele evento a um endpoint. Guarda o código HTTP que seu servidor respondeu (responseStatusCode), o tempo de resposta, o corpo retornado e quantas tentativas foram feitas. Se você tem três endpoints inscritos no mesmo tipo, um evento gera três despachos.

Esta é uma operação de leitura paginada. Ela não cria nem altera nada — é segura para repetir. A resposta segue o padrão de paginação por offset/limit da API e inclui _links (HATEOAS) e o bloco merchant. Para reenviar um evento que falhou, veja Reenviar evento.

Quando usar

• Você recebeu um webhook estranho (ou nenhum) e quer ver o que a Selectwin realmente tentou entregar.
• Seu endpoint ficou fora do ar e você precisa achar os eventos com status=failed para reenviar.
• Suporte/conciliação: confirmar que um evento específico (transaction.approved de uma transação) foi gerado e entregue.
• Inspecionar a resposta HTTP do seu próprio servidor (responseStatusCode, responseBody, responseTime) para depurar timeouts ou erros 5xx do seu lado.

Quando não usar: para reagir a mudanças de estado em tempo real (use o webhook em si) ou para buscar o objeto de negócio completo (consulte o recurso de origem, ex.: GET /v1/transactions/{id}).

Requisição

Headers

Por ser uma leitura sem corpo, não envie Content-Type nem X-Idempotency-Key. Nunca use Authorization: Bearer/Basic — a Selectwin autentica apenas pelo header SelectKey.

Parâmetros de query

Todos são opcionais. Combine-os livremente; os filtros são aplicados em conjunto (E lógico).

Atenção aos nomes: os parâmetros são eventid e resourceid (tudo minúsculo), e o status válido é delivered/failed — não succeeded. Datas seguem ISO 8601 em UTC; veja Convenções.

Exemplos curl

Listar os eventos mais recentes:

curl https://api.selectwin.io/v1/webhooks/events?limit=20&sort=descending \
  -H "SelectKey: sl_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ"

Encontrar tudo que falhou para reenviar:

curl "https://api.selectwin.io/v1/webhooks/events?status=failed&sort=descending" \
  -H "SelectKey: sl_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ"

Todos os eventos de uma transação específica, em abril de 2026:

curl "https://api.selectwin.io/v1/webhooks/events?resourceid=tra_987654321&daterangegte=2026-04-01T00:00:00Z&daterangelte=2026-04-30T23:59:59Z" \
  -H "SelectKey: sl_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ"

Resposta

200 OK com um objeto paginado. O array data traz os eventos; cada evento embute seus dispatches[]. O bloco merchant e _links ficam na raiz.

{
  "offset": 0,
  "limit": 20,
  "total": 100,
  "hasMore": true,
  "page": {
    "current": 1,
    "total": 5,
    "offset": { "first": 0, "prev": 0, "next": 20, "last": 80 }
  },
  "data": [
    {
      "id": "wbh_01hqzvabc",
      "resource": "transaction",
      "type": "transaction.approved",
      "attempts": 1,
      "lastAttempt": "2026-04-12T17:56:33.000Z",
      "description": "Transaction approved event",
      "requestPayload": {
        "id": "tra_987654321",
        "amount": 1500,
        "status": "approved"
      },
      "updatedAt": "2026-04-12T17:56:33.000Z",
      "createdAt": "2026-04-12T17:56:32.000Z",
      "source": "api",
      "dispatches": [
        {
          "id": "wdi_01hqzvabc",
          "status": "success",
          "endpoint": "https://webhooks.mydomain.com/selectwin",
          "attempts": 1,
          "lastAttemptAt": "2026-04-12T17:56:33.100Z",
          "successAt": "2026-04-12T17:56:33.150Z",
          "responseStatusCode": 200,
          "responseTime": 120,
          "responseBody": "OK",
          "correlationId": "corr_abc123",
          "updatedAt": "2026-04-12T17:56:33.150Z",
          "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/events",
      "method": "GET"
    }
  }
}

Envelope de paginação

Campos do evento (data[])

Campos do despacho (data[].dispatches[])

Erros

A resposta de erro segue o envelope padrão; trate sempre pelo error.code, nunca pela message. Veja Tratamento de erros e o Catálogo de códigos de erro.

Boas práticas

• Não use isto como polling. Receba os webhooks no seu servidor; recorra a esta listagem só para auditoria, diagnóstico e reenvio.
• Pagine pelos campos certos. Avance com offset += limit enquanto hasMore for true, ou use page.offset.next. Mantenha limit em até 100.
• Filtre antes de paginar. Combine status=failed com resourceid ou um daterange* para reduzir o conjunto em vez de varrer todas as páginas.
• Diagnostique pelo despacho, não pelo evento. O motivo de uma entrega falhar está em dispatches[] — olhe responseStatusCode, responseTime e responseBody para distinguir um 5xx do seu lado de um timeout.
• Use a janela de datas certa. daterange cobre um único dia; para intervalos, combine daterangegte + daterangelte (lembre que gt/lt são exclusivos e gte/lte inclusivos).
• Trate IDs como opacos. Guarde id (wbh_…) e requestPayload.id como strings inteiras; não faça parsing nem confie no comprimento.
• Da listagem ao reenvio. Achou um evento com status=failed? Pegue o id e dispare o reenvio.

Veja também

• Visão geral de Webhook Events — o recurso, o modelo do objeto e o ciclo de vida.
• Reenviar evento — reentrega manual de um evento por id.
• Catálogo de eventos — todos os type disponíveis.
• Verificando assinaturas de webhook — valide a autenticidade no seu servidor.
• Paginação e Convenções — padrões transversais.