Payloads de Eventos de Webhook

Toda entrega de webhook carrega um corpo JSON com a mesma estrutura de envelope, independentemente do tipo de evento. Esta página explica cada campo e os dois mais importantes de acertar na sua integração: sequence e applicationId.

O envelope

{
  "id": "event_01HXPA3M9R7DEF456",
  "type": "transfer.succeeded",
  "apiVersion": "v2",
  "originalCreateDate": "2026-08-07T14:05:30.000Z",
  "livemode": true,
  "sequence": 5,
  "data": {
    "id": "payout_d243ab2b1de4447d8a046d87fefe58cf",
    "type": "transfer",
    "applicationId": "application_1324354657",
    "customerId": "customer_f31121c389624d3697cbf3ea8830b7a4",
    "transferType": "oneTimeTransfer",
    "previousStatus": "processing",
    "previousStatusAt": "2026-08-07T14:02:15.000Z",
    "status": "succeeded",
    "statusAt": "2026-08-07T14:05:30.000Z",
    "cause": null
  }
}

Campo	Descrição
`id`	Identificador único do evento (prefixo `event_`). Estável em todas as entregas e replays do mesmo evento — use-o como sua chave de idempotência.
`type`	O nome do evento do catálogo de eventos, por exemplo `customer.approved`.
`apiVersion`	A versão do esquema do evento (atualmente `v2`). É distinta da `apiVersion` datada que você define no endpoint de webhook.
`originalCreateDate`	Timestamp ISO 8601 de quando a mudança de estado do recurso que disparou este evento ocorreu originalmente. Nunca muda, mesmo em replays — ao contrário do cabeçalho `Sphere-Timestamp`, que reflete quando cada tentativa de entrega foi enviada.
`livemode`	`true` para eventos de produção, `false` para eventos em modo de teste.
`sequence`	Inteiro monotonicamente crescente usado para ordenar os eventos de um recurso. Veja abaixo.
`data`	O assunto do evento: o ID do recurso, seu `applicationId`, o status anterior, o novo status e um campo `cause` reservado para motivos de falha (atualmente sempre `null`). Os campos variam ligeiramente por recurso — consulte o catálogo de eventos.

O corpo é idêntico byte a byte em todas as entregas e replays do mesmo evento. Tudo o que varia por tentativa de entrega — o ID da entrega, o contador de tentativas, o timestamp, a assinatura — fica nos cabeçalhos HTTP.

Eventos, entregas e tentativas

Três registros distintos estão por trás de cada webhook que chega até você, e cada um carrega seu próprio identificador e seus próprios timestamps. Mantê-los separados é a chave para reconciliar os vários timestamps e a lógica de sequence abaixo.

Registro	O que é	Identificador	Timestamps	Onde você o vê
Evento	O fato imutável de que algo aconteceu. Um por ocorrência, compartilhado por todos os endpoints que o recebem.	`id` no corpo (`event_...`)	`originalCreateDate` — quando a mudança de estado do recurso que disparou o evento ocorreu originalmente. Nunca muda, mesmo em replay.	O corpo do payload; `GET /v2/events`
Entrega de evento	O roteamento de um evento para um endpoint. Dois endpoints inscritos produzem duas entregas do mesmo evento.	Cabeçalho `Sphere-Delivery-Id` (`eventDelivery_...`)	`deliveredAt` — quando seu endpoint confirmou com um `2xx`.	Os cabeçalhos; o objeto `delivery` na API de Eventos
Tentativa de entrega	Uma única requisição HTTP ao seu endpoint — o envio original ou um replay manual.	Contador `Sphere-Delivery-Attempt` e cabeçalho `Sphere-Delivery-Type`; `attempts[]` no detalhe do evento	Cabeçalho `Sphere-Timestamp` / `attemptedAt` — quando esta requisição específica foi enviada. Renovado a cada tentativa.	Os cabeçalhos; `GET /v2/events/{id}`

A divisão segue uma regra: tudo o que é intrínseco ao evento — id, type, sequence, originalCreateDate, data — fica no corpo e nunca muda; tudo o que descreve esta requisição HTTP específica — ID da entrega, número da tentativa, tipo da tentativa, timestamp, assinatura — fica nos cabeçalhos e é regenerado a cada tentativa.

Ao ordenar o estado do negócio, confie no evento, nunca na tentativa. Um replay de um evento antigo chega com um Sphere-Timestamp novo (para passar nas verificações de tolerância da assinatura), mas seu sequence e originalCreateDate ainda refletem quando a mudança de estado realmente ocorreu. Ordenar por Sphere-Timestamp faria um evento antigo reenviado parecer mais novo do que os eventos que o sucederam — ordenar por sequence mantém os replays inofensivos.

Payloads carregam a mudança de estado, não o recurso completo

Os payloads de webhook contêm deliberadamente o mínimo de que você precisa para reagir: o ID do recurso e a transição de previousStatus para status. Eles não contêm o objeto completo do recurso. A maioria das reações — rotear pelo novo status, atualizar a linha correspondente no seu próprio banco de dados, notificar sua equipe de operações — funciona apenas com o payload. Quando precisar do recurso completo (critérios de verificação completos, detalhes de conta bancária, valores da transferência), busque-o no endpoint GET do recurso:

# The payload told you payout_d243... succeeded; fetch the full object:
curl https://api.spherepay.co/v2/transfer/payout_d243ab2b1de4447d8a046d87fefe58cf \
  -H "Authorization: Bearer {{api_key}}"

Como o payload é mínimo e imutável, um evento reenviado nunca carrega dados obsoletos se passando por atuais — ele descreve uma transição que aconteceu em originalCreateDate. Se você sempre fizer GET no recurso para obter seu estado atual antes de executar efeitos colaterais, os replays são inofensivos.

O campo `sequence`

sequence é um inteiro monotonicamente crescente com escopo em uma única instância de recurso — um contador por cliente, um por transferência, e assim por diante, indexado por data.id. Ele é atribuído quando o evento é criado e nunca muda, de modo que reflete a ordem verdadeira em que as mudanças de estado ocorreram, mesmo quando as entregas chegam fora de ordem. Como a ordem de entrega não é garantida, use sequence para se proteger contra atualizações obsoletas:

Armazene o maior sequence que você já processou por instância de recurso — por exemplo, uma coluna lastSphereSequence na linha do cliente no seu próprio banco de dados.
Quando um evento chegar, compare seu sequence com o valor armazenado para aquele data.id.
Se incoming.sequence <= stored.sequence, o evento é obsoleto ou duplicado — confirme com um 2xx e pule a atualização.
Caso contrário, aplique a atualização e armazene o novo sequence.

Você não precisa de um contador global na sua conta — apenas de rastreamento por entidade, colocalizado com o estado do recurso que você já mantém.

Não presuma que os valores de sequence que você recebe são contíguos. Se o seu endpoint assina um subconjunto dos eventos de um recurso, você observará lacunas — use a comparação de obsolescência <= acima, nunca detecção de lacunas.

Por que ambos `sequence` e `originalCreateDate`?

Eles respondem a perguntas diferentes. originalCreateDate diz quando uma mudança de estado aconteceu — tempo de relógio, útil para exibição, trilhas de auditoria e consultas por janela de tempo. Mas o tempo de relógio é uma chave de ordenação pouco confiável: duas transições rápidas no mesmo recurso podem ocorrer tão próximas que seus timestamps colidem, e uma comparação de timestamps não tem como desempatar. sequence existe para tornar a ordenação inequívoca — um inteiro estritamente crescente por instância de recurso, de forma que quaisquer dois eventos do mesmo recurso sempre tenham uma ordem definida, não importa quão próximos tenham ocorrido. Regra prática: ordene e deduplique por sequence; exiba e audite por originalCreateDate.

O campo `applicationId`

Todo payload inclui data.applicationId — a aplicação do SpherePay à qual o evento pertence. Endpoints de webhook são registrados por aplicação, e os eventos só são entregues para recursos pertencentes à aplicação do endpoint. Isso é mais importante quando você opera múltiplas aplicações do SpherePay que compartilham uma mesma URL receptora de webhooks. Registrar a mesma URL em duas aplicações é perfeitamente válido — mas seu handler então recebe eventos de ambas, e o endpoint de cada aplicação tem seu próprio segredo de assinatura. Use applicationId para rotear cada evento ao contexto de aplicação correto no seu sistema (e para selecionar o segredo correto ao verificar assinaturas).

Você encontra o ID de cada aplicação na página Settings do dashboard de integrador do SpherePay.

Onboarding

Transferências

Automação

Webhooks

Dados de referência

Operacional

Payloads de Eventos de Webhook

O envelope

Eventos, entregas e tentativas

Payloads carregam a mudança de estado, não o recurso completo

O campo `sequence`

Por que ambos `sequence` e `originalCreateDate`?

O campo `applicationId`

​O envelope

​Eventos, entregas e tentativas

​Payloads carregam a mudança de estado, não o recurso completo

​O campo sequence

​Por que ambos sequence e originalCreateDate?

​O campo applicationId

O envelope

Eventos, entregas e tentativas

Payloads carregam a mudança de estado, não o recurso completo

O campo `sequence`

Por que ambos `sequence` e `originalCreateDate`?

O campo `applicationId`