Gerenciamento de Endpoints de Webhook

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:

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

{
  "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"
}

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 de cada entrega. Cada endpoint tem seu próprio segredo distinto; segredos nunca são compartilhados entre endpoints.

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.

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.

Para uma migração sem lacunas:

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

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.

Listar e recuperar endpoints

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.

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.*,*.

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

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.

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.

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.

Onboarding

Transferências

Automação

Webhooks

Dados de referência

Operacional

Gerenciamento de Endpoints de Webhook

Registrar um endpoint

Atualizando um endpoint: exclua e recrie

Listar e recuperar endpoints

Excluir um endpoint

Limites de endpoints

Estados do endpoint

Erros

​Registrar um endpoint

​Atualizando um endpoint: exclua e recrie

​Listar e recuperar endpoints

​Excluir um endpoint

​Limites de endpoints

​Estados do endpoint

​Erros

Registrar um endpoint

Atualizando um endpoint: exclua e recrie

Listar e recuperar endpoints

Excluir um endpoint

Limites de endpoints

Estados do endpoint

Erros