Gestión de Endpoints de Webhook

Un endpoint de webhook es una URL que registras con SpherePay junto con la lista de eventos que debe recibir. Esta página cubre el ciclo de vida completo del endpoint: crear un endpoint, listar y recuperar endpoints, y eliminarlos.

Registrar un endpoint

Crea un endpoint con 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	Requerido	Descripción
`url`	Sí	La URL a la que SpherePay entrega los eventos. Debe ser HTTPS en modo live. Máximo 2,048 caracteres.
`subscribedEvents`	Sí	Uno o más nombres de evento del catálogo de eventos, o un comodín: `` (todos los eventos) o un comodín de recurso como `customer.` o `transfer.*`.
`apiVersion`	Sí	Una fecha de versión de API en formato `YYYY-MM-DD`. Debe ser una fecha de calendario válida y no debe estar en el futuro.
`description`	No	Etiqueta de texto libre, hasta 500 caracteres.
`metadata`	No	Pares clave-valor para tu propia contabilidad — por ejemplo, para rastrear los endpoints registrados dentro de tu sistema.

La respuesta devuelve el endpoint y su secreto de firma:

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

El secret (con prefijo whsec_) se devuelve exactamente una vez, en la respuesta de creación. Nunca es devuelto por solicitudes GET y no puede recuperarse más tarde. Guárdalo de forma segura — lo necesitas para verificar la firma en cada entrega. Cada endpoint tiene su propio secreto distinto; los secretos nunca se comparten entre endpoints.

Los endpoints recién creados quedan enabled de inmediato y comienzan a recibir los eventos que coincidan con su suscripción.

Actualizar un endpoint: eliminar y recrear

Actualmente no existe una operación de actualización para los endpoints de webhook. Para cambiar la URL de un endpoint, sus eventos suscritos o cualquier otra propiedad, elimina el endpoint y crea uno nuevo. Lo mismo aplica para rotar un secreto de firma — eliminar un endpoint invalida su secreto, y el endpoint de reemplazo recibe uno nuevo.

Las actualizaciones de endpoints in situ llegarán pronto — una versión futura te permitirá modificar la URL y las suscripciones de un endpoint existente sin recrearlo. Hasta entonces, usa el flujo de eliminar y recrear que se describe a continuación.

Para una migración sin interrupciones:

Crea el nuevo endpoint con la configuración actualizada. Ambos endpoints ahora reciben eventos.
Confirma que el nuevo endpoint está recibiendo y verificando entregas.
Elimina el endpoint antiguo.

Durante el paso 1 ambos endpoints reciben los mismos eventos, por lo que tus handlers deben ser idempotentes — deduplica usando el id del evento en el cuerpo del payload.

Listar y recuperar endpoints

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

Parámetros de consulta para listar:

Parámetro	Descripción
`page`	Número de página, comenzando en `1` (por defecto `1`).
`limit`	Resultados por página (por defecto `10`, máximo `100`).
`status`	Filtra por estado del endpoint: `enabled`, `disabled` o `errored`.
`subscribedEvents`	Nombres de eventos separados por comas; devuelve los endpoints suscritos a al menos uno de ellos. Se aceptan valores comodín (``, `customer.`, `transfer.*`).

El filtro subscribedEvents compara literalmente contra la lista de suscripción de cada endpoint — no expande los comodines. Filtrar por transfer.* devuelve los endpoints que se suscribieron con el comodín transfer.* en sí, no los endpoints suscritos a eventos individuales como transfer.succeeded (y viceversa). Para encontrar todos los endpoints que recibirían un evento dado, filtra por ambas formas: subscribedEvents=transfer.succeeded,transfer.*,*.

Las respuestas de listado usan la envoltura de paginación estándar de SpherePay: { "data": [...], "page", "limit", "total", "totalPages", "hasNext", "hasPrevious" }. Recupera un solo endpoint con GET /v2/webhook-endpoints/{id}. El campo secret nunca se incluye.

Eliminar un endpoint

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

La eliminación devuelve 204 No Content, transiciona el endpoint al estado deleted, invalida su secreto de firma y detiene todas las entregas futuras. Esto es terminal y no se puede deshacer — para reanudar la entrega, crea un nuevo endpoint.

Límites de endpoints

Cada aplicación puede tener como máximo 6 endpoints de webhook activos — endpoints en el estado enabled, disabled o errored. Los endpoints eliminados no cuentan para el límite. Excederlo devuelve 409 Conflict.

Estados de endpoint

Estado	Significado
`enabled`	Recibiendo entregas. El estado inicial después del registro.
`disabled`	No recibe entregas.
`errored`	Reservado para el manejo de fallos de entrega en una versión futura.
`deleted`	Terminal. El endpoint ya no existe para propósitos de entrega y su secreto es inválido.

Solo los endpoints enabled reciben entregas.

Las entregas fallidas no deshabilitan tu endpoint. En la versión actual, SpherePay nunca cambia el estado de un endpoint en función de los resultados de entrega: si tu endpoint devuelve una respuesta no 2xx o agota el tiempo de espera, la entrega individual se marca como failed y no ocurre ningún reintento automático, pero el endpoint permanece enabled y continúa recibiendo los eventos siguientes. Recupera los eventos perdidos con un reenvío manual.

Errores

Condición	Estado HTTP	Descripción
Nombre de evento desconocido en `subscribedEvents`	`400`	El tipo de evento no está en el catálogo publicado.
`apiVersion` inválido	`400`	No es una fecha de calendario `YYYY-MM-DD` válida, o es una fecha en el futuro.
Endpoint no encontrado	`404`	El ID del endpoint de webhook no existe.
Límite de endpoints excedido	`409`	La aplicación ya tiene 6 endpoints activos.

Incorporación

Transferencias

Automatización

Webhooks

Datos de referencia

Operacional

Gestión de Endpoints de Webhook

Registrar un endpoint

Actualizar un endpoint: eliminar y recrear

Listar y recuperar endpoints

Eliminar un endpoint

Límites de endpoints

Estados de endpoint

Errores

​Registrar un endpoint

​Actualizar un endpoint: eliminar y recrear

​Listar y recuperar endpoints

​Eliminar un endpoint

​Límites de endpoints

​Estados de endpoint

​Errores

Registrar un endpoint

Actualizar un endpoint: eliminar y recrear

Listar y recuperar endpoints

Eliminar un endpoint

Límites de endpoints

Estados de endpoint

Errores