Listar eventos

Este endpoint lista os eventos de webhook gerados na sua conta, com paginação e filtros. Cada item traz os dispatches aninhados (tentativas de entrega). É a ferramenta para monitorar o histórico de ev

Visão Geral

Este endpoint lista os eventos de webhook gerados na sua conta, com paginação e filtros. Cada item traz os dispatches aninhados (tentativas de entrega). É a ferramenta para monitorar o histórico de eventos e diagnosticar falhas.

Descrição

A listagem oferece uma visão das notificações geradas. Você pode filtrar por tipo de evento, recurso, status de entrega, endpoint de destino e intervalo de datas.

Requisição

GET /v1/webhooks/events

Cabeçalho: SelectKey: sk_live_... (ou sk_test_...). Escopo necessário: webhooks:read.

Parâmetros de Consulta

Parâmetro	Tipo	Descrição	Exemplo
`offset`	integer	Posição inicial (padrão `0`)	`0`
`limit`	integer	Máximo de registros (padrão `20`, máximo `100`)	`20`
`sort`	string	Expressão de ordenação (aceita `ascending`/`descending`)	`descending`
`type`	string	Filtra pelo tipo de evento (ver Catálogo)	`transaction.approved`
`resource`	string	Filtra pelo recurso afetado	`transaction`
`resourceId`	string	Filtra pelo ID do recurso	`tra_987654321`
`status`	string	Filtra pelo status de entrega: `delivered` ou `failed`	`failed`
`eventId`	string	Filtra por um ID de evento específico	`wbh_01hqzvabc`
`endpoint`	string	Filtra pela URL exata do endpoint de destino	`https://webhooks.mydomain.com/selectwin`
`daterange`	string (date)	Filtra por um único dia de criação	`2026-06-20`
`daterangegt` / `daterangegte`	string (date-time)	Criado após / a partir de	`2026-06-01T00:00:00Z`
`daterangelt` / `daterangelte`	string (date-time)	Criado antes de / até	`2026-06-30T23:59:59Z`

Os aliases legados resourceid e eventid (minúsculos) também são aceitos.

Resposta

Sucesso (200 OK)

Envelope paginado (com merchant/_links no root); cada item de data é um evento com dispatches[] aninhados.

{
  "offset": 0,
  "limit": 20,
  "total": 100,
  "page": {
    "offset": { "first": 0, "prev": 0, "next": 20, "last": 80 },
    "current": 1,
    "total": 5
  },
  "hasMore": true,
  "data": [
    {
      "id": "wbh_01hqzvabc",
      "type": "transaction.approved",
      "resource": "transaction",
      "resourceId": "tra_987654321",
      "source": "automatic",
      "delivered": true,
      "attempts": 1,
      "data": {
        "id": "tra_987654321",
        "amount": 1500,
        "status": "approved"
      },
      "createdAt": "2026-06-20T17:56:32.000Z",
      "dispatches": [
        {
          "id": "wdi_01hqzvabc",
          "eventId": "wbh_01hqzvabc",
          "endpointId": "wbe_01hqzvabc",
          "endpoint": "https://webhooks.mydomain.com/selectwin",
          "status": "success",
          "attempts": 1,
          "responseStatusCode": 200,
          "responseTime": 120,
          "nextAttemptAt": null,
          "lastAttemptAt": "2026-06-20T17:56:33.100Z",
          "successAt": "2026-06-20T17:56:33.150Z",
          "createdAt": "2026-06-20T17:56:33.000Z"
        }
      ]
    }
  ],
  "merchant": {
    "name": "Seller Name",
    "merchantId": "bus_1234567890",
    "isSubAccount": false
  },
  "_links": {
    "self": {
      "href": "https://api.selectwin.io/v1/webhooks/events",
      "method": "GET",
      "description": "List all webhook events."
    }
  }
}

Atributos do Envelope

Atributo	Tipo	Descrição
`offset` / `limit` / `total` / `page` / `hasMore`		Paginação padrão
`data`	array	Eventos com `dispatches[]` aninhados
`merchant`	object	Bloco do lojista
`_links`	object	HATEOAS (`self`)

Atributos do Evento (item de data)

Atributo	Tipo	Descrição
`id`	string	ID do evento (`wbh_*`)
`type`	string	Tipo do evento
`resource`	string	Recurso afetado
`resourceId`	string \| null	ID público do recurso
`source`	string	Origem (`automatic`, `api`)
`delivered`	boolean	Se a entrega foi concluída com sucesso
`attempts`	integer	Total de tentativas
`data`	objeto	Objeto do recurso no momento do evento
`createdAt`	string (ISO)	Data de criação
`dispatches`	array	Tentativas de entrega (ver Dispatches)

Exemplo de Uso

Consulta Básica

GET /v1/webhooks/events

Filtrar por Status de Entrega

GET /v1/webhooks/events?status=failed

Filtrar por Tipo de Evento

GET /v1/webhooks/events?type=transaction.approved

Filtrar por Endpoint e Ordenar Decrescente

GET /v1/webhooks/events?endpoint=https://webhooks.mydomain.com/selectwin&sort=descending

Códigos de Erro

Código HTTP	Descrição
401	Não autorizado (`SelectKey` ausente/inválida)
403	Sem o escopo `webhooks:read`
500	Erro interno do servidor

Listar eventos

On this page