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

# Gestión de Endpoints de Webhook

> Registra endpoints de webhook, suscríbete a eventos y entiende los límites de endpoints, sus estados y el modelo de actualización de eliminar y recrear.

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

```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              | 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](/es/concepts/webhooks/event-catalog), 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:

```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>
  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](/es/concepts/webhooks/verifying-signatures) en cada entrega. Cada endpoint tiene su propio secreto distinto; los secretos nunca se comparten entre endpoints.
</Warning>

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.

<Info>
  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.
</Info>

Para una migración sin interrupciones:

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

<Note>
  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.
</Note>

## Listar y 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 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.*`). |

<Note>
  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.*,*`.
</Note>

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

```bash theme={"dark"}
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.

<Note>
  **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](/es/concepts/webhooks/events-and-replays).
</Note>

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