Gestionar Webhooks

Administra tus webhooks mediante la API de Aloha Pay.

Listar Webhooks

Obtén todos los webhooks configurados en tu cuenta.

Endpoint

GET /v1/webhooks

Autenticación

Requiere API Key con el ability webhooks:read.

Ejemplo de Solicitud

cURL
JavaScript

curl https://api.alohapay.co/api/external/v1/webhooks \
  -H "X-API-Key: tu_api_key"

const response = await fetch(
  'https://api.alohapay.co/api/external/v1/webhooks',
  {
    headers: {
      'X-API-Key': 'tu_api_key'
    }
  }
);
const data = await response.json();
console.log(data.data);

Respuesta Exitosa (200)

{
  "success": true,
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "url": "https://tu-servidor.com/webhooks/alohapay",
      "description": "Webhook principal",
      "events": ["payment.completed", "payment.failed"],
      "is_active": true,
      "created_at": "2025-12-04T10:00:00Z"
    }
  ]
}

Obtener Webhook

Obtén los detalles de un webhook específico.

Endpoint

GET /v1/webhooks/{id}

Autenticación

Requiere API Key con el ability webhooks:read.

Parámetros de Ruta

Parámetro	Tipo	Descripción
`id`	string	ID único del webhook

curl https://api.alohapay.co/api/external/v1/webhooks/550e8400-e29b-41d4-a716-446655440000 \
  -H "X-API-Key: tu_api_key"

const webhookId = '550e8400-e29b-41d4-a716-446655440000';
const response = await fetch(
  `https://api.alohapay.co/api/external/v1/webhooks/${webhookId}`,
  {
    headers: {
      'X-API-Key': 'tu_api_key'
    }
  }
);
const data = await response.json();

Respuesta Exitosa (200)

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "url": "https://tu-servidor.com/webhooks/alohapay",
    "description": "Webhook principal",
    "events": ["payment.completed", "payment.failed"],
    "is_active": true,
    "created_at": "2025-12-04T10:00:00Z"
  }
}

Crear Webhook

Crea un nuevo webhook para recibir notificaciones.

Endpoint

POST /v1/webhooks

Autenticación

Requiere API Key con el ability webhooks:write.

Cuerpo de la Solicitud

{
  "url": "https://tu-servidor.com/webhooks/alohapay",
  "description": "Webhook principal de producción",
  "events": ["payment.completed", "payment.failed", "payment_link.expired"]
}

Parámetros

Parámetro	Tipo	Requerido	Descripción
`url`	string	Sí	URL HTTPS donde recibirás los webhooks
`description`	string	No	Descripción del webhook
`events`	string[]	Sí	Lista de eventos a suscribir

Eventos Disponibles

payment.completed
payment.failed
payment_link.cancelled
payment_link.expired

Ejemplo de Solicitud

cURL
JavaScript

curl -X POST https://api.alohapay.co/api/external/v1/webhooks \
  -H "X-API-Key: tu_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://tu-servidor.com/webhooks/alohapay",
    "description": "Webhook principal de producción",
    "events": ["payment.completed", "payment.failed"]
  }'

const response = await fetch(
  'https://api.alohapay.co/api/external/v1/webhooks',
  {
    method: 'POST',
    headers: {
      'X-API-Key': 'tu_api_key',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      url: 'https://tu-servidor.com/webhooks/alohapay',
      description: 'Webhook principal de producción',
      events: ['payment.completed', 'payment.failed']
    })
  }
);
const data = await response.json();

// IMPORTANTE: Guarda el secret
console.log('Secret:', data.data.secret);

Respuesta Exitosa (201)

{
  "success": true,
  "message": "Webhook endpoint created successfully",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "url": "https://tu-servidor.com/webhooks/alohapay",
    "description": "Webhook principal de producción",
    "events": ["payment.completed", "payment.failed"],
    "secret": "whsec_a1b2c3d4e5f6g7h8i9j0...",
    "is_active": true,
    "created_at": "2025-12-04T10:00:00Z"
  }
}

Actualizar Webhook

Actualiza la configuración de un webhook existente.

Endpoint

PUT /v1/webhooks/{id}

Autenticación

Requiere API Key con el ability webhooks:write.

Parámetros de Ruta

Parámetro	Tipo	Descripción
`id`	string	ID único del webhook

Cuerpo de la Solicitud

{
  "url": "https://nuevo-servidor.com/webhooks",
  "events": ["payment.completed"],
  "is_active": true
}

Parámetros

Parámetro	Tipo	Requerido	Descripción
`url`	string	No	Nueva URL del webhook
`description`	string	No	Nueva descripción
`events`	string[]	No	Nueva lista de eventos
`is_active`	boolean	No	Activar/desactivar el webhook

Ejemplo de Solicitud

cURL
JavaScript

curl -X PUT https://api.alohapay.co/api/external/v1/webhooks/550e8400-e29b-41d4-a716-446655440000 \
  -H "X-API-Key: tu_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://nuevo-servidor.com/webhooks",
    "events": ["payment.completed"],
    "is_active": true
  }'

const webhookId = '550e8400-e29b-41d4-a716-446655440000';
const response = await fetch(
  `https://api.alohapay.co/api/external/v1/webhooks/${webhookId}`,
  {
    method: 'PUT',
    headers: {
      'X-API-Key': 'tu_api_key',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      url: 'https://nuevo-servidor.com/webhooks',
      events: ['payment.completed'],
      is_active: true
    })
  }
);
const data = await response.json();

Respuesta Exitosa (200)

{
  "success": true,
  "message": "Webhook endpoint updated successfully",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "url": "https://nuevo-servidor.com/webhooks",
    "description": "Webhook principal de producción",
    "events": ["payment.completed"],
    "is_active": true,
    "created_at": "2025-12-04T10:00:00Z"
  }
}

Desactivar Webhook

Desactiva temporalmente un webhook sin eliminarlo.

Ejemplo

cURL

curl -X PUT https://api.alohapay.co/api/external/v1/webhooks/550e8400-e29b-41d4-a716-446655440000 \
  -H "X-API-Key: tu_api_key" \
  -H "Content-Type: application/json" \
  -d '{"is_active": false}'

Eliminar Webhook

Elimina permanentemente un webhook.

Endpoint

DELETE /v1/webhooks/{id}

Autenticación

Requiere API Key con el ability webhooks:write.

Ejemplo de Solicitud

cURL
JavaScript

curl -X DELETE https://api.alohapay.co/api/external/v1/webhooks/550e8400-e29b-41d4-a716-446655440000 \
  -H "X-API-Key: tu_api_key"

const webhookId = '550e8400-e29b-41d4-a716-446655440000';
const response = await fetch(
  `https://api.alohapay.co/api/external/v1/webhooks/${webhookId}`,
  {
    method: 'DELETE',
    headers: {
      'X-API-Key': 'tu_api_key'
    }
  }
);

Respuesta Exitosa (200)

{
  "success": true,
  "message": "Webhook endpoint deleted successfully"
}

Rotar Secret

Genera un nuevo secret para el webhook. El secret anterior deja de funcionar inmediatamente.

Endpoint

POST /v1/webhooks/{id}/rotate-secret

Autenticación

Requiere API Key con el ability webhooks:write.

Ejemplo de Solicitud

cURL
JavaScript

curl -X POST https://api.alohapay.co/api/external/v1/webhooks/550e8400-e29b-41d4-a716-446655440000/rotate-secret \
  -H "X-API-Key: tu_api_key"

const webhookId = '550e8400-e29b-41d4-a716-446655440000';
const response = await fetch(
  `https://api.alohapay.co/api/external/v1/webhooks/${webhookId}/rotate-secret`,
  {
    method: 'POST',
    headers: {
      'X-API-Key': 'tu_api_key'
    }
  }
);
const data = await response.json();

// IMPORTANTE: Actualiza tu servidor con el nuevo secret
console.log('Nuevo Secret:', data.data.secret);

Respuesta Exitosa (200)

{
  "success": true,
  "message": "Webhook secret rotated successfully",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "secret": "whsec_nuevo_secret_xyz..."
  }
}

Errores Comunes

API Key Inválida (401)

{
  "success": false,
  "code": "INVALID_API_KEY",
  "message": "Invalid API key configuration"
}

Permisos Insuficientes (403)

{
  "success": false,
  "code": "insufficient_scope",
  "message": "API Key does not have the required ability"
}

Webhook No Encontrado (404)

{
  "success": false,
  "code": "NOT_FOUND",
  "message": "Webhook endpoint not found"
}

Error de Validación (422)

{
  "success": false,
  "code": "VALIDATION_FAILED",
  "message": "Validation failed",
  "errors": {
    "url": ["The url must be a valid HTTPS URL."],
    "events": ["The events field is required."]
  }
}

Tabla de Errores

Código HTTP	Código de Error	Descripción
401	`INVALID_API_KEY`	API Key inválida o expirada
401	`missing_api_key`	No se proporcionó API Key
403	`insufficient_scope`	La API Key no tiene el ability requerido
404	`NOT_FOUND`	Webhook no encontrado
422	`VALIDATION_FAILED`	Error de validación en los parámetros