Webhooks

Los Webhooks te permiten recibir notificaciones HTTP automáticas cuando ocurren eventos importantes en tu cuenta de Aloha Pay.

¿Qué son los Webhooks?

Los webhooks son notificaciones HTTP que Aloha Pay envía a tu servidor cuando ocurre un evento importante. En lugar de que tu sistema consulte constantemente “¿ya pagó el cliente?”, nosotros te avisamos inmediatamente cuando el pago se completa.

Sin Webhooks (Polling):
┌──────────────┐                    ┌─────────────┐
│  Tu Sistema  │ ───── ¿Pagó? ────► │  Aloha Pay  │
│              │ ◄──── No ───────── │             │
│              │ ───── ¿Pagó? ────► │             │
│              │ ◄──── No ───────── │             │
│              │ ───── ¿Pagó? ────► │             │  (Repetir cada 5 seg...)
│              │ ◄──── Sí! ──────── │             │
└──────────────┘                    └─────────────┘

Con Webhooks:
┌──────────────┐                    ┌─────────────┐
│  Tu Sistema  │                    │  Aloha Pay  │
│              │                    │             │
│   (espera)   │ ◄──── ¡Pagó! ───── │             │  (Te avisamos al instante)
│              │                    │             │
└──────────────┘                    └─────────────┘

¿Por qué usar Webhooks?

Polling (sin webhooks)	Webhooks
Consultas constantes a la API	Solo recibes cuando hay eventos
Consume recursos de ambos lados	Eficiente y en tiempo real
Delay entre consultas (5-30 seg)	Notificación instantánea
Puede alcanzar rate limits	Sin límites por consultas
Código más complejo	Arquitectura más simple

Flujo de un Pago con Webhooks

1. Tu sistema crea un Payment Link
   ┌──────────────┐                         ┌─────────────┐
   │  Tu Sistema  │ ── POST /payment-links ─► │  Aloha Pay  │
   │              │ ◄─ { id, checkout_url } ── │             │
   └──────────────┘                         └─────────────┘

2. Rediriges al cliente al checkout
   ┌──────────────┐                         ┌─────────────┐
   │   Cliente    │ ── Abre checkout_url ───► │   Checkout  │
   │              │    Completa el pago       │             │
   └──────────────┘                         └─────────────┘

3. Aloha Pay te notifica vía webhook
   ┌──────────────┐                         ┌─────────────┐
   │  Tu Sistema  │ ◄── POST /tu-webhook ──── │  Aloha Pay  │
   │              │    { payment.completed }  │             │
   │              │ ── 200 OK ───────────────► │             │
   └──────────────┘                         └─────────────┘

4. Tu sistema procesa el pago
   - Marca la orden como pagada
   - Envía email de confirmación
   - Libera el producto/servicio

Dos Formas de Recibir Webhooks

Opción A: Webhook Global (Recomendado)

Registras UN endpoint que recibe TODOS los eventos de tu cuenta:

# Registrar webhook global
curl -X POST https://api.alohapay.co/api/external/v1/webhooks \
  -H "X-API-Key: tu_api_key" \
  -d '{
    "url": "https://tu-servidor.com/webhooks/alohapay",
    "events": ["payment.completed", "payment.failed"]
  }'

Ventajas:

• Configuración única
• Todos los pagos notifican al mismo endpoint
• Fácil de mantener

Cuándo usar:

• Tienes un sistema centralizado
• Quieres recibir todos los eventos en un lugar

Opción B: Webhook por Payment Link

Defines una URL específica para CADA payment link:

# Al crear el payment link
curl -X POST https://api.alohapay.co/api/external/v1/payment-links \
  -H "X-API-Key: tu_api_key" \
  -d '{
    "amount": 100.00,
    "currency": "USD",
    "description": "Orden #1234",
    "webhook_url": "https://tu-servidor.com/webhooks/orden/1234"
  }'

Ventajas:

• URL específica por transacción
• Puedes incluir información en la URL
• Útil para sistemas distribuidos

Cuándo usar:

• Cada transacción necesita un endpoint diferente
• Quieres pasar contexto en la URL

Usando Ambas Opciones

Puedes usar las dos opciones al mismo tiempo. Si un payment link tiene webhook_url Y tienes un webhook global, recibirás el evento en AMBOS.

Tu sistema debe manejar esto con idempotencia (ver Mejores Prácticas).

Permisos Requeridos (Abilities)

Para trabajar con Webhooks, tu API Key necesita los siguientes abilities:

Operación	Ability
Listar	webhooks:read
Consultar	webhooks:read
Crear	webhooks:write
Actualizar	webhooks:write
Eliminar	webhooks:write
Rotar Secret	webhooks:write

URL Base

Todos los endpoints de Webhooks utilizan la siguiente URL base:

https://api.alohapay.co/api/external/v1/webhooks

Endpoints Disponibles

Método	Endpoint	Descripción
GET	/v1/webhooks	Listar todos los webhooks
GET	/v1/webhooks/{id}	Obtener detalles de un webhook
POST	/v1/webhooks	Crear un nuevo webhook
PUT	/v1/webhooks/{id}	Actualizar un webhook
DELETE	/v1/webhooks/{id}	Eliminar un webhook
POST	/v1/webhooks/{id}/rotate-secret	Rotar el secret del webhook

Próximos Pasos

• Guía de Integración - Implementa webhooks paso a paso
• Eventos - Conoce los eventos disponibles y su formato
• Verificación de Firma - Asegura tus webhooks
• Gestionar Webhooks - Administra webhooks vía API
• Mejores Prácticas - Recomendaciones y troubleshooting