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

# Visão Geral de Webhooks

> Receba notificações em tempo real quando clientes, transferências e outros recursos do SpherePay mudarem de estado — em vez de consultar atualizações por polling.

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`](/pt-BR/concepts/webhooks/managing-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](/pt-BR/concepts/webhooks/verifying-signatures), 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](/pt-BR/concepts/webhooks/events-and-replays):

| Conceito                 | Significado                                                                                                                                      |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Evento**               | Um fato sobre algo que aconteceu no SpherePay — um por ocorrência, imutável após a criação. Identificado por um ID `event_` no corpo do payload. |
| **Entrega de evento**    | Um evento sendo roteado para um dos seus endpoints de webhook. Se dois endpoints assinam o mesmo tipo de evento, um evento produz duas entregas. |
| **Tentativa de entrega** | Uma única requisição HTTP do SpherePay para o seu endpoint. Cada tentativa registra o código de resposta, a latência e se foi bem-sucedida.      |

Cada registro carrega seu próprio identificador e seus próprios timestamps — consulte [Eventos, entregas e tentativas](/pt-BR/concepts/webhooks/event-payloads) 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](/pt-BR/concepts/webhooks/events-and-replays) 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`](/pt-BR/concepts/webhooks/event-payloads) 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](/pt-BR/concepts/webhooks/event-payloads).

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

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

<CardGroup cols={2}>
  <Card title="Gerencie endpoints de webhook" icon="plug" href="/pt-BR/concepts/webhooks/managing-endpoints">
    Registre, liste e exclua endpoints de webhook, e entenda os limites e estados dos endpoints.
  </Card>

  <Card title="Payloads de eventos" icon="braces" href="/pt-BR/concepts/webhooks/event-payloads">
    A estrutura do envelope, o campo `sequence` e como `applicationId` delimita o escopo de cada evento.
  </Card>

  <Card title="Catálogo de eventos" icon="list" href="/pt-BR/concepts/webhooks/event-catalog">
    Todos os assuntos de evento que você pode assinar, com gatilhos e exemplos de payload.
  </Card>

  <Card title="Verifique assinaturas" icon="shield-check" href="/pt-BR/concepts/webhooks/verifying-signatures">
    Autentique entregas com HMAC-SHA256 — com snippets em Python, JavaScript, Go, Java e C#.
  </Card>

  <Card title="Eventos e replays" icon="rotate-cw" href="/pt-BR/concepts/webhooks/events-and-replays">
    Navegue pelo seu histórico de eventos, inspecione tentativas de entrega e reenvie entregas com falha.
  </Card>
</CardGroup>