Consultando Eventos e Reenviando Entregas

Todo evento que o SpherePay cria — e toda tentativa de entregá-lo — é registrado e consultável. Use a API de Eventos para auditar o que aconteceu, diagnosticar entregas com falha e reenviar qualquer entrega ao seu endpoint. Visões do Dashboard para navegar e reenviar eventos chegarão em breve; hoje esses controles estão na API.

Listar eventos

curl "https://api.spherepay.co/v2/events?type=transfer.*&status=failed&page=1&limit=10" \
  -H "Authorization: Bearer {{api_key}}"

Parâmetro	Descrição
`type`	Filtro de tipo de evento — um nome exato (`transfer.succeeded`), um wildcard de recurso (`transfer.`) ou ``.
`status`	Filtra pelo status de entrega: `queued`, `delivering`, `delivered` ou `failed`.
`webhookEndpointId`	Apenas eventos com uma entrega para o endpoint informado.
`createdStart` / `createdEnd`	Limites ISO 8601 inclusivos sobre o horário de criação do evento.
`page` / `limit`	Paginação (padrões `1` / `10`, limite máximo `100`).

Cada item da lista resume o evento e sua entrega mais recente:

{
  "data": [
    {
      "id": "event_01HXPA3M9R7DEF456",
      "type": "transfer.succeeded",
      "createdAt": "2026-08-07T14:05:30.123Z",
      "sequence": 5,
      "delivery": {
        "id": "eventDelivery_2351653173",
        "webhookEndpointId": "whk_01HXP9TN3J2ABC",
        "status": "delivered",
        "attemptsUsed": 1,
        "deliveredAt": "2026-08-07T14:05:31.821Z",
        "latestAttempt": {
          "type": "original",
          "success": true,
          "responseCode": 200
        }
      }
    }
  ],
  "page": 1,
  "limit": 10,
  "total": 1,
  "totalPages": 1,
  "hasNext": false,
  "hasPrevious": false
}

Para encontrar tudo o que precisa de atenção, filtre por status=failed. Um responseCode de null em uma tentativa significa que seu endpoint não respondeu de forma alguma — um timeout ou erro de rede, e não um erro HTTP.

Status de entrega

Status	Significado
`queued`	A entrega está aguardando para ser enviada.
`delivering`	Uma requisição HTTP ao seu endpoint está em andamento.
`delivered`	Seu endpoint confirmou com uma resposta `2xx`.
`failed`	A tentativa mais recente falhou — resposta não-`2xx`, ou nenhuma resposta em até 15 segundos. Recuperável via replay.

Recuperar um evento

GET /v2/events/{id} retorna o evento completo mais cada entrega e cada tentativa — incluindo a resposta que seu endpoint retornou:

curl https://api.spherepay.co/v2/events/event_01HXPA3M9R7DEF456 \
  -H "Authorization: Bearer {{api_key}}"

Cada tentativa registra type (original ou replay), attemptedAt, success, responseCode, responseBody (truncado em 200 caracteres, capturado em falhas para ajudar na depuração) e latencyMs.

Se você tem em mãos um cabeçalho Sphere-Delivery-Id de uma entrega que recebeu, esse é o ID da entrega — você pode usá-lo para correlacionar uma requisição chegando aos seus servidores com os registros de entrega e tentativa exibidos aqui.

Reenviando uma entrega

O SpherePay faz exatamente uma tentativa automática de entrega por evento por endpoint — não há retentativas automáticas. Quando uma entrega falha (seu endpoint estava fora do ar, excedeu o tempo limite ou retornou um erro), você decide quando reenviá-la com POST /v2/events/replay/{eventDeliveryId}, usando o ID da entrega (não o ID do evento):

curl -X POST https://api.spherepay.co/v2/events/replay/eventDelivery_2351653173 \
  -H "Authorization: Bearer {{api_key}}"

Um replay reenvia o payload idêntico byte a byte para o mesmo endpoint, com um Sphere-Timestamp e uma Sphere-Signature novos e os cabeçalhos Sphere-Delivery-Type: replay e Sphere-Replay-Reason: manual. Seu caminho de código de verificação é idêntico para originais e replays. Um replay bem-sucedido transiciona a entrega para delivered; um replay com falha a deixa em failed e registra mais uma tentativa. De qualquer forma, o histórico completo de tentativas é preservado.

Replays são entregues pelo menos uma vez (at-least-once) em cima do que seu endpoint já recebeu, e você pode reenviar uma entrega que já teve sucesso. Garanta que seu handler deduplique pelo id do evento e aplique a verificação de obsolescência via sequence para que os replays sejam sempre seguros.

Recuperando-se de indisponibilidade

Se o seu endpoint ficou fora do ar por um período:

Liste os eventos com status=failed e createdStart/createdEnd cobrindo a janela da indisponibilidade.
Reenvie cada entrega com falha via POST /v2/events/replay/{eventDeliveryId}.
Seu tratamento de sequence descartará automaticamente qualquer evento reenviado que já tenha sido superado.

Alternativamente, como os payloads são mínimos, você pode simplesmente buscar novamente o estado atual dos recursos afetados com seus endpoints GET e reconciliar diretamente.

Onboarding

Transferências

Automação

Webhooks

Dados de referência

Operacional

Consultando Eventos e Reenviando Entregas

Listar eventos

Status de entrega

Recuperar um evento

Reenviando uma entrega

Recuperando-se de indisponibilidade

​Listar eventos

​Status de entrega

​Recuperar um evento

​Reenviando uma entrega

​Recuperando-se de indisponibilidade

Listar eventos

Status de entrega

Recuperar um evento

Reenviando uma entrega

Recuperando-se de indisponibilidade