Conheça o Webhooks v2

A movimentação de dinheiro é assíncrona, e os momentos importantes acontecem no tempo de outra pessoa. Uma análise de compliance é concluída. Um banco de destino faz a liquidação.

Acompanhar o progresso de uma transferência na Sphere costumava significar fazer consultas periódicas. A cobertura de webhooks não incluía o status das transferências, então as equipes escreviam o loop, o GET, uma comparação com o que havia sido armazenado da última vez e o tratamento de erros para quando a requisição falhava. Funcionava, mas impunha um limite fixo à rapidez com que você podia reagir e uma carga constante sobre uma API que, na maior parte do tempo, não tinha nada de novo a dizer.

O Webhooks v2 já está disponível. O mecanismo de entrega foi reconstruído, o catálogo de eventos é novo e os endpoints agora podem ser gerenciados pela API. Dezoito eventos cobrem os ciclos de vida de verificação de clientes e de transferências, e a Sphere entrega cada um deles ao seu endpoint no momento em que acontece. Seu handler agora é executado quando o estado muda, e não no seu intervalo de polling.

A cobertura é intencional: um evento em cada etapa do ciclo de vida da transferência, incluindo o momento em que um depósito chega, e um evento em cada etapa da verificação de clientes.

O que já está disponível

Antes, as transferências só podiam ser acompanhadas chamando GET /v2/transfer/{id} periodicamente. Agora existem 14 eventos de transferência que cobrem toda a máquina de estados: transfer.created, transfer.fundsReceived, transfer.processing e transfer.succeeded no fluxo de sucesso, e um evento distinto para cada resultado de falha, devolução e reembolso, incluindo transfer.failed, transfer.returned, transfer.refunded e transfer.expired.

Quatro eventos cobrem a verificação de clientes. customer.created é disparado uma vez, quando o registro é criado. customer.pending, customer.approved e customer.rejected são disparados uma vez por perfil de verificação a cada transição, então um cliente com dois perfis gera dois fluxos de eventos independentes.

Você faz a assinatura por endpoint, seja de nomes de eventos específicos ou de um curinga como transfer.*.

Por que o payload é pequeno

Há uma decisão de design que vale a pena explicar aqui, porque ela define como você vai escrever seu handler.

O corpo de um webhook poderia trazer o recurso inteiro. Optamos por não fazer isso, e essa escolha define como você escreve seu handler. Cada evento traz o ID do recurso, o status anterior e o novo com seus timestamps, os IDs relacionais necessários para associar o evento aos seus próprios registros e uma causa estruturada quando algo falha:
‍
{
 "id": "event_01HXP9ZK7Q4ABC123",
 "type": "transfer.succeeded",
 "apiVersion": "v2",
 "livemode": true,
 "sequence": 5,
 "data": {
   "id": "payout_d243ab2b1de4447d8a046d87fefe58cf",
   "type": "transfer",
   "customerId": "customer_f31121c389624d3697cbf3ea8830b7a4",
   "applicationId": "application_26b980e989d94e6d975144f7e21f282f",
   "transferType": "oneTimeTransfer",
   "previousStatus": "processing",
   "previousStatusAt": "2026-04-23T14:04:30.000Z",
   "status": "succeeded",
   "statusAt": "2026-04-23T14:05:30.000Z",
   "cause": null
 }
}

O raciocínio é que a maioria dos handlers não precisa do objeto completo. Atualizar uma linha ou notificar um canal de operações funciona apenas com o corpo. Um payload grande significaria enviar, a cada entrega, campos que você nunca lê. Quando sua lógica precisar do recurso completo, você faz um GET nele. Preferimos que você faça essa chamada de forma deliberada a pagar por ela em cada evento.

As falhas dizem o porquê

Todo evento de falha terminal traz uma cause estruturada. Um cliente rejeitado chega com um valor como identity_verification_failure, document_mismatch, incomplete_information ou restricted_jurisdiction. Uma transferência com falha chega com insufficient_funds, recipient_bank_rejection, invalid_recipient ou quote_expired.

São valores de enum, não texto livre. Você pode criar ramificações e rotear com base neles sem escrever um parser para strings que talvez reformulemos no futuro.

A ordenação é um único inteiro

Redes reordenam as coisas, e um sistema de webhooks que ignora isso joga o problema para você.

Todo evento traz um sequence: um inteiro monotonicamente crescente, com escopo no recurso individual e no que o seu endpoint assina. Eventos de tipos que você não assinou não o incrementam, então você nunca verá uma lacuna e ficará se perguntando o que perdeu.

O padrão de reconciliação é uma única comparação com uma coluna em uma linha que você já mantém:

if (event.sequence <= customer.lastSphereSequence) return ack();

Sem contador global, sem serviço de ordenação, sem fila própria. Ocasionalmente, você pode receber o mesmo evento mais de uma vez; o id do evento é estável em todas as entregas do mesmo evento e é a sua chave de idempotência.

Como verificar uma entrega

Cada endpoint tem seu próprio segredo de assinatura, retornado uma única vez quando você cria o endpoint e nunca mais. Toda entrega é assinada com HMAC-SHA256 sobre o timestamp e o corpo bruto:

const expected = crypto.createHmac("sha256", secret)
 .update(`${headers["sphere-timestamp"]}.${rawBody}`)
 .digest("hex");

Compare esse valor com o esquema v1= no header Sphere-Signature e rejeite qualquer entrega cujo Sphere-Timestamp tenha mais de cinco minutos. Faça a verificação sobre os bytes brutos, e não sobre um corpo re-serializado. Uma ida e volta por JSON vai alterá-los, e a assinatura não vai bater.

Retorne um 2xx em até quinze segundos e consideraremos o evento entregue.

Implementações de verificação prontas para copiar e colar em TypeScript, Python e Go estão na documentação.

Gerenciando endpoints

Registre um endpoint com POST /v2/webhook-endpoints, listando os eventos que você deseja. Cada conta pode ter até seis.

GET /v2/events retorna o que enviamos para você. Filtre por endpoint, tipo de evento, status de entrega ou intervalo de datas, e abra qualquer evento para ver cada tentativa de entrega com seu código de resposta e latência. São os mesmos dados que vão alimentar o dashboard, expostos primeiro como API para que você possa construir reconciliação e alertas diretamente sobre eles.

Já usa webhooks?

Seus endpoints existentes continuam funcionando. O Webhooks v2 é uma superfície separada e versionada. Nada é ativado por baixo dos seus endpoints existentes. Crie um endpoint v2 pela API, valide-o com o seu handler e desative o antigo quando estiver pronto. Os endpoints existentes terão suporte por pelo menos doze meses, e daremos um aviso claro com bastante antecedência antes que isso mude. As etapas de migração estão na documentação.

O que vem a seguir

Um dashboard de webhooks chega logo depois deste lançamento. Ele vai oferecer o log de eventos como uma interface navegável, um botão para disparar eventos de teste no seu endpoint antes de entrar em produção e replay com um clique para qualquer entrega que não tenha chegado. O replay chega junto com ele.

Depois disso: novas tentativas automáticas e monitoramento da saúde dos endpoints, para que uma breve indisponibilidade do seu lado se resolva sem que ninguém precise intervir. Em seguida, atualização de endpoints sem precisar recriá-los, rotação de segredos, uma API de replay e SDKs oficiais para TypeScript, Python e Go. Eventos de documentos e de serviços virão depois.

Comece aqui
Dúvidas? Fale com support@spherepay.co.