APIDestinos de webhooks
GET /v1/webhook-endpoints
Destinos de webhooks de la empresa, sólo para consultarlos. El alta, la edición, la baja, la rotación del secreto y la reactivación se hacen en el panel: v1 no tiene API para eso.
| Dato | Valor |
|---|---|
| Método y ruta | GET /v1/webhook-endpoints |
| Servidor | https://widget.fital.xyz |
operationId | listWebhookEndpoints |
| Acceso | Llave con el scope webhooks:read |
| Firma de petición | No aplica |
| Idempotencia | No aplica |
- Sólo consulta. El alta, la edición, la baja, la rotación del secreto y la reactivación de un destino se hacen en el panel, también en
v1: un destino decide a dónde sale tu información, y el panel exige sesión, rol y bitácora. Ver Dar de alta un destino.
Encabezados de la petición
| Encabezado | Obligatorio | Descripción |
|---|---|---|
Authorization | Sí | Bearer y tu llave. |
X-Fital-Scenario | No | Sólo simuladores: elige la respuesta que quieres practicar. |
Respuestas correctas
200 Correcto
| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
data | lista de objeto | Sí | Destinos de webhooks de la empresa. |
data[].created_at | texto o null | Sí | Fecha de creación. ISO 8601 en UTC. |
data[].events | lista de texto | Sí | Tipos suscritos. Vacío: todos. |
data[].id | texto | Sí | Identificador del destino. |
data[].status | texto | Sí | Estado del destino. active: Recibe eventos. disabled: Dejó de recibir eventos tras 3 días seguidos de fallos. Se reactiva en el panel. paused: Valor reservado. Hoy ningún flujo lo asigna. |
data[].url | texto | Sí | URL https que recibe los eventos. |
Valores de data[].status
| Valor | Significado |
|---|---|
active | Recibe eventos. |
disabled | Dejó de recibir eventos tras 3 días seguidos de fallos. Se reactiva en el panel. |
paused | Valor reservado. Hoy ningún flujo lo asigna. |
{
"data": [
{
"created_at": "2026-11-04T18:00:00.000Z",
"events": [
"payment.completed",
"payment.failed"
],
"id": "3f0c2d1e-7a54-4b1f-9c0e-1a2b3c4d5e6f",
"status": "active",
"url": "https://empresa-ejemplo.com/webhooks/fital"
}
]
}Encabezados de la respuesta
| Encabezado | Contenido |
|---|---|
X-Request-Id | Identificador de la petición. Cítalo con soporte. |
Retry-After | Segundos a esperar, con 429 y a veces con 503. |
Errores
Todos usan la forma de Errores: error.code, message, request_id, details, retryable y docs_url. Decide por code.
| HTTP | Código | Cuándo sale | retryable |
|---|---|---|---|
| 400 | invalid_request (sólo cuenta de prueba) | El encabezado X-Fital-Scenario trae un escenario desconocido. | false |
| 401 | invalid_api_key | La llave falta, está mal formada, venció o fue revocada, o la empresa está suspendida. | false |
| 401 | wrong_environment | La llave es de otro ambiente. | false |
| 403 | forbidden_scope | La llave no tiene el scope de esta operación. details.required_scope lo nombra. | false |
| 403 | ip_not_allowed | La IP de origen no está activa en la lista de esa llave. | false |
| 429 | rate_limited | Superaste un límite de peticiones. Llega con Retry-After. | true |
| 500 | internal_error | Fallo nuestro. El resultado de la petición no se conoce. | true |
| 503 | service_unavailable | El servicio no está disponible por ahora. El resultado de la petición no se conoce. | true |
Ejemplos de error
400 invalid_request:
{
"error": {
"code": "invalid_request",
"message": "Petición inválida",
"request_id": "0123456789abcdef0123456789abcdef",
"details": {
"fields": {
"limit": "Entre 1 y 100"
}
},
"retryable": false,
"docs_url": "https://merchants.fital.xyz/docs/errores/#invalid_request"
}
}401 invalid_api_key:
{
"error": {
"code": "invalid_api_key",
"message": "Credencial inválida",
"request_id": "0123456789abcdef0123456789abcdef",
"details": {},
"retryable": false,
"docs_url": "https://merchants.fital.xyz/docs/errores/#invalid_api_key"
}
}403 forbidden_scope:
{
"error": {
"code": "forbidden_scope",
"message": "La llave no tiene permiso para esta operación",
"request_id": "0123456789abcdef0123456789abcdef",
"details": {
"required_scope": "webhooks:read"
},
"retryable": false,
"docs_url": "https://merchants.fital.xyz/docs/errores/#forbidden_scope"
}
}429 rate_limited:
{
"error": {
"code": "rate_limited",
"message": "Demasiadas peticiones",
"request_id": "0123456789abcdef0123456789abcdef",
"details": {},
"retryable": true,
"docs_url": "https://merchants.fital.xyz/docs/errores/#rate_limited"
}
}500 internal_error:
{
"error": {
"code": "internal_error",
"message": "Error interno",
"request_id": "0123456789abcdef0123456789abcdef",
"details": {},
"retryable": true,
"docs_url": "https://merchants.fital.xyz/docs/errores/#internal_error"
}
}503 service_unavailable:
{
"error": {
"code": "service_unavailable",
"message": "Servicio no disponible",
"request_id": "0123456789abcdef0123456789abcdef",
"details": {},
"retryable": true,
"docs_url": "https://merchants.fital.xyz/docs/errores/#service_unavailable"
}
}Reintentos
Es una lectura: repetirla no tiene efecto.
429 rate_limited: Espera lo que indiqueRetry-Aftery repite.500 internal_error: Repite con espera exponencial.503 service_unavailable: Repite con espera exponencial. RespetaRetry-Aftersi viene.
Ver Reintentos y Límites.
Muestras
Variables de estas muestras: simulador público, sin cuenta
Define esto en tu terminal. Con estos valores las muestras corren tal cual contra el simulador público:
export FITAL_API="https://widget.fital.xyz/explorar/v1"
export FITAL_KEY="sk_test_sandbox_publica"En la cuenta de prueba o en producción cambia la base, la llave y el secreto, y sustituye los id de ejemplo por los tuyos. Ver Ambientes.
curl -sS "$FITAL_API/webhook-endpoints" \
-H "Authorization: Bearer $FITAL_KEY"