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

# Gerenciamento de Endpoints de Webhook

> Registre endpoints de webhook, assine eventos e entenda os limites e estados dos endpoints e o modelo de atualização por exclusão e recriação.

Um endpoint de webhook é uma URL que você registra no SpherePay junto com a lista de eventos que ele deve receber. Esta página cobre o ciclo de vida completo do endpoint: criar um endpoint, listar e recuperar endpoints e excluí-los.

## Registrar um endpoint

Crie um endpoint com `POST /v2/webhook-endpoints`:

```bash theme={"dark"}
curl -X POST https://api.spherepay.co/v2/webhook-endpoints \
  -H "Authorization: Bearer {{api_key}}" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://api.example.com/sphere-webhook",
    "subscribedEvents": ["customer.approved", "customer.rejected", "transfer.*"],
    "apiVersion": "2026-08-01",
    "description": "Production onboarding and transfer events",
    "metadata": { "team": "payments", "environment": "prod" }
  }'
```

| Campo              | Obrigatório | Descrição                                                                                                                                                                                        |
| ------------------ | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `url`              | Sim         | A URL para a qual o SpherePay entrega os eventos. Deve ser HTTPS em modo live. Máximo de 2.048 caracteres.                                                                                       |
| `subscribedEvents` | Sim         | Um ou mais nomes de evento do [catálogo de eventos](/pt-BR/concepts/webhooks/event-catalog), ou um wildcard: `*` (todos os eventos) ou um wildcard de recurso como `customer.*` ou `transfer.*`. |
| `apiVersion`       | Sim         | Uma data de versão da API no formato `YYYY-MM-DD`. Deve ser uma data de calendário válida e não pode estar no futuro.                                                                            |
| `description`      | Não         | Rótulo de texto livre, até 500 caracteres.                                                                                                                                                       |
| `metadata`         | Não         | Pares chave-valor para o seu próprio controle — por exemplo, para rastrear os endpoints registrados dentro do seu sistema.                                                                       |

A resposta retorna o endpoint e seu segredo de assinatura:

```json theme={"dark"}
{
  "id": "whk_01HXP9TN3J2ABC",
  "url": "https://api.example.com/sphere-webhook",
  "subscribedEvents": ["customer.approved", "customer.rejected", "transfer.*"],
  "status": "enabled",
  "apiVersion": "2026-08-01",
  "secret": "whsec_9f8a7b6c5d4e3f2a1b0c9d8e7f6a5b4c",
  "description": "Production onboarding and transfer events",
  "metadata": { "team": "payments", "environment": "prod" },
  "createdAt": "2026-08-07T10:00:00Z",
  "updatedAt": "2026-08-07T10:00:00Z"
}
```

<Warning>
  O `secret` (com prefixo `whsec_`) é retornado **exatamente uma vez**, na resposta de criação. Ele nunca é retornado por requisições `GET` e não pode ser recuperado depois. Armazene-o com segurança — você precisa dele para [verificar a assinatura](/pt-BR/concepts/webhooks/verifying-signatures) de cada entrega. Cada endpoint tem seu próprio segredo distinto; segredos nunca são compartilhados entre endpoints.
</Warning>

Endpoints recém-criados ficam `enabled` imediatamente e começam a receber os eventos que correspondem à sua assinatura.

## Atualizando um endpoint: exclua e recrie

Atualmente **não existe operação de atualização** para endpoints de webhook. Para mudar a URL de um endpoint, os eventos assinados ou qualquer outra propriedade, exclua o endpoint e crie um novo. O mesmo vale para rotacionar um segredo de assinatura — excluir um endpoint invalida seu segredo, e o endpoint substituto recebe um novo.

<Info>
  Atualizações in-place de endpoints chegarão em breve — uma versão futura permitirá modificar a URL e as assinaturas de um endpoint existente sem recriá-lo. Até lá, use o fluxo de exclusão e recriação abaixo.
</Info>

Para uma migração sem lacunas:

1. Crie o novo endpoint com a configuração atualizada. Ambos os endpoints agora recebem eventos.
2. Confirme que o novo endpoint está recebendo e verificando as entregas.
3. Exclua o endpoint antigo.

<Note>
  Durante a etapa 1, ambos os endpoints recebem os mesmos eventos, então seus handlers devem ser idempotentes — deduplique pelo `id` do evento no corpo do payload.
</Note>

## Listar e recuperar endpoints

```bash theme={"dark"}
curl "https://api.spherepay.co/v2/webhook-endpoints?page=1&limit=10" \
  -H "Authorization: Bearer {{api_key}}"
```

Parâmetros de consulta da listagem:

| Parâmetro          | Descrição                                                                                                                                                  |
| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `page`             | Número da página, começando em `1` (padrão `1`).                                                                                                           |
| `limit`            | Resultados por página (padrão `10`, máximo `100`).                                                                                                         |
| `status`           | Filtra pelo estado do endpoint: `enabled`, `disabled` ou `errored`.                                                                                        |
| `subscribedEvents` | Nomes de evento separados por vírgula; retorna endpoints inscritos em pelo menos um deles. Valores wildcard (`*`, `customer.*`, `transfer.*`) são aceitos. |

<Note>
  O filtro `subscribedEvents` compara **literalmente** contra a lista de assinatura de cada endpoint — ele não expande wildcards. Filtrar por `transfer.*` retorna os endpoints que assinaram o próprio wildcard `transfer.*`, e não os endpoints inscritos em eventos individuais como `transfer.succeeded` (e vice-versa). Para encontrar todos os endpoints que receberiam um determinado evento, filtre pelas duas formas: `subscribedEvents=transfer.succeeded,transfer.*,*`.
</Note>

As respostas de listagem usam o envelope padrão de paginação do SpherePay: `{ "data": [...], "page", "limit", "total", "totalPages", "hasNext", "hasPrevious" }`.

Recupere um único endpoint com `GET /v2/webhook-endpoints/{id}`. O campo `secret` nunca é incluído.

## Excluir um endpoint

```bash theme={"dark"}
curl -X DELETE https://api.spherepay.co/v2/webhook-endpoints/{{webhook_endpoint_id}} \
  -H "Authorization: Bearer {{api_key}}"
```

A exclusão retorna `204 No Content`, transiciona o endpoint para o estado `deleted`, invalida seu segredo de assinatura e interrompe todas as entregas futuras. **Isso é terminal e não pode ser desfeito** — para retomar a entrega, crie um novo endpoint.

## Limites de endpoints

Cada aplicação pode ter no máximo **6 endpoints de webhook ativos** — endpoints nos estados `enabled`, `disabled` ou `errored`. Endpoints excluídos não contam para o limite. Exceder o limite retorna `409 Conflict`.

## Estados do endpoint

| Estado     | Significado                                                                         |
| ---------- | ----------------------------------------------------------------------------------- |
| `enabled`  | Recebendo entregas. O estado inicial após o registro.                               |
| `disabled` | Não está recebendo entregas.                                                        |
| `errored`  | Reservado para tratamento de falhas de entrega em uma versão futura.                |
| `deleted`  | Terminal. O endpoint não existe mais para fins de entrega e seu segredo é inválido. |

Apenas endpoints `enabled` recebem entregas.

<Note>
  **Entregas com falha não desabilitam seu endpoint.** Na versão atual, o SpherePay nunca muda o estado de um endpoint com base nos resultados das entregas: se o seu endpoint retornar uma resposta não-`2xx` ou exceder o tempo limite, a entrega individual é marcada como `failed` e nenhuma retentativa automática ocorre, mas o endpoint permanece `enabled` e continua recebendo os eventos subsequentes. Recupere eventos perdidos com um [replay manual](/pt-BR/concepts/webhooks/events-and-replays).
</Note>

## Erros

| Condição                                          | Status HTTP | Descrição                                                                             |
| ------------------------------------------------- | ----------- | ------------------------------------------------------------------------------------- |
| Nome de evento desconhecido em `subscribedEvents` | `400`       | O tipo de evento não está no catálogo publicado.                                      |
| `apiVersion` inválida                             | `400`       | Não é uma data de calendário válida no formato `YYYY-MM-DD`, ou é uma data no futuro. |
| Endpoint não encontrado                           | `404`       | O ID do endpoint de webhook não existe.                                               |
| Limite de endpoints excedido                      | `409`       | A aplicação já tem 6 endpoints ativos.                                                |