Skip to main content
Webhooks permitem que o SpherePay notifique sua aplicação no momento em que algo acontece — um cliente é aprovado, uma transferência é concluída, fundos são recebidos — para que você não precise mais consultar endpoints GET em busca de mudanças. Você registra um endpoint HTTPS, escolhe os eventos que lhe interessam, e o SpherePay entrega um payload JSON assinado a esse endpoint sempre que um desses eventos ocorre.

​
Como funciona

  1. Registre um endpoint de webhook. Chame POST /v2/webhook-endpoints com sua URL e a lista de eventos que deseja assinar. A resposta inclui um segredo de assinatura — armazene-o com segurança; ele é exibido exatamente uma vez.
  2. Um evento ocorre. Um recurso na sua aplicação muda de estado — por exemplo, uma transferência passa de processing para succeeded.
  3. O SpherePay entrega o evento. O SpherePay envia um POST HTTP para cada endpoint habilitado inscrito naquele tipo de evento. A requisição carrega um payload assinado que descreve a transição de estado.
  4. Você verifica e processa. Seu handler verifica a assinatura, aplica a mudança de estado e responde com um código de status 2xx em até 15 segundos.

​
Conceitos principais

O sistema de webhooks do SpherePay rastreia três registros distintos para cada notificação, e os três são visíveis por meio da API de Eventos: Cada registro carrega seu próprio identificador e seus próprios timestamps — consulte Eventos, entregas e tentativas para ver como eles se mapeiam ao corpo do payload e aos cabeçalhos, e em quais confiar ao ordenar estado.

​
Semântica de entrega

Entender estas garantias é essencial para construir um consumidor confiável:
  • Entrega pelo menos uma vez (at-least-once). Ocasionalmente você pode receber o mesmo evento mais de uma vez. Deduplique usando o id do evento no corpo — ele é estável em todas as entregas e replays do mesmo evento.
  • Sem retentativas automáticas. O SpherePay faz exatamente uma tentativa de entrega por evento por endpoint. Se o seu endpoint retornar uma resposta não-2xx, ou não responder em até 15 segundos, a entrega é marcada como failed e o SpherePay não a reenvia automaticamente. Você pode reenviar uma entrega com falha a qualquer momento pela API de Eventos.
  • A ordem de entrega não é garantida. Replays, workers em paralelo e variações de rede podem causar chegadas fora de ordem. Todo payload carrega um campo sequence para que você detecte e descarte atualizações obsoletas.
  • Payloads mínimos. Os payloads de eventos descrevem a transição de estado — o status anterior e o novo status — e não o recurso completo. Quando precisar do objeto completo, chame o endpoint GET do recurso. Consulte Payloads de eventos.
Como não há retentativas automáticas na versão atual, torne seu handler de webhook rápido e resiliente: confirme com um 2xx imediatamente após verificar a assinatura e faça o processamento pesado de forma assíncrona. Um handler lento que exceda a janela de 15 segundos fará com que as entregas sejam marcadas como failed.

​
Respondendo a uma entrega

Retorne qualquer código de status 2xx para confirmar o recebimento. Qualquer outra coisa — incluindo redirecionamentos, que o SpherePay não segue — marca a entrega como failed.

​
Explore

Gerencie endpoints de webhook

Registre, liste e exclua endpoints de webhook, e entenda os limites e estados dos endpoints.

Payloads de eventos

A estrutura do envelope, o campo sequence e como applicationId delimita o escopo de cada evento.

Catálogo de eventos

Todos os assuntos de evento que você pode assinar, com gatilhos e exemplos de payload.

Verifique assinaturas

Autentique entregas com HMAC-SHA256 — com snippets em Python, JavaScript, Go, Java e C#.

Eventos e replays

Navegue pelo seu histórico de eventos, inspecione tentativas de entrega e reenvie entregas com falha.
Última modificação em 11 de agosto de 2026