> ## Documentation Index
> Fetch the complete documentation index at: https://docs.spherepay.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Payloads de Eventos de Webhook

> A estrutura de todo payload de webhook — os campos do envelope, como o campo sequence ordena eventos e como applicationId delimita o escopo de cada evento.

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

```json theme={"dark"}
{
  "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](/pt-BR/concepts/webhooks/event-catalog), 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](#o-campo-sequence).                                                                                                                                                                                 |
| `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](/pt-BR/concepts/webhooks/event-catalog). |

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](/pt-BR/concepts/webhooks/verifying-signatures).

## 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`](/pt-BR/concepts/webhooks/events-and-replays) |
| **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}`](/pt-BR/concepts/webhooks/events-and-replays) |

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.

<Warning>
  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.
</Warning>

## 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:

```bash theme={"dark"}
# 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}}"
```

<Tip>
  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.
</Tip>

## 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:

1. 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.
2. Quando um evento chegar, compare seu `sequence` com o valor armazenado para aquele `data.id`.
3. Se `incoming.sequence <= stored.sequence`, o evento é obsoleto ou duplicado — confirme com um `2xx` e pule a atualização.
4. 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.

<Note>
  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.
</Note>

### 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).

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