Eventos

Conoce todos los eventos disponibles y el formato de los datos que recibirás en cada webhook.

Eventos Disponibles

Solicitudes de Pago

Evento	Cuándo se dispara
`payment.completed`	El cliente completó el pago exitosamente
`payment.failed`	El pago falló (rechazado, cancelado por cliente)
`payment_link.cancelled`	Cancelaste el payment link manualmente
`payment_link.expired`	El payment link expiró sin ser pagado

Pagos con Tarjeta

Evento	Cuándo se dispara
`card_payment.completed`	El cliente completó el pago con tarjeta exitosamente
`card_payment_link.cancelled`	Cancelaste el enlace de pago con tarjeta manualmente

Headers de los Webhooks

Cada webhook incluye los siguientes headers HTTP:

Header	Descripción	Ejemplo
`Content-Type`	Siempre JSON	`application/json`
`User-Agent`	Identificador de Aloha Pay	`AlohaPay-Webhooks/1.0`
`X-Webhook-Id`	ID único de esta entrega	`del_abc123...`
`X-Webhook-Timestamp`	Unix timestamp del envío	`1733310600`
`X-Webhook-Signature`	Firma HMAC-SHA256	`sha256=abc123...`

Estructura General del Payload

Todos los webhooks siguen esta estructura:

{
  "id": "wh_evt_uuid",
  "event": "payment.completed",
  "created": "2025-12-04T10:30:00Z",
  "api_version": "2025-12-03",
  "source": "subscription",
  "data": {
    "object": {
      // Datos del recurso (pago o payment link)
    }
  }
}

Campo	Tipo	Descripción
`id`	string	ID único del evento webhook
`event`	string	Tipo de evento
`created`	string	Fecha del evento (ISO 8601)
`api_version`	string	Versión de la API
`source`	string	Origen del webhook (`subscription` o `inline`)
`data.object`	object	Datos del recurso relacionado

Payload por Evento

payment.completed

Se envía cuando un cliente completa exitosamente un pago.

{
  "id": "wh_evt_550e8400-e29b-41d4-a716-446655440000",
  "event": "payment.completed",
  "created": "2025-12-04T10:30:00Z",
  "api_version": "2025-12-03",
  "source": "subscription",
  "data": {
    "object": {
      "id": "payin_uuid",
      "amount": 100.0,
      "currency": "USD",
      "status": "completed",
      "customer_data": {
        "name": "Juan Pérez",
        "email": "juan@ejemplo.com"
      },
      "created_at": "2025-12-04T10:29:45Z",
      "completed_at": "2025-12-04T10:30:00Z",
      "payment_method": "bank_transfer",
      "description": "Orden #1234"
    }
  }
}

payment.failed

Se envía cuando un pago falla o es rechazado.

{
  "id": "wh_evt_550e8400-e29b-41d4-a716-446655440001",
  "event": "payment.failed",
  "created": "2025-12-04T10:30:00Z",
  "api_version": "2025-12-03",
  "source": "subscription",
  "data": {
    "object": {
      "id": "payin_uuid",
      "amount": 100.0,
      "currency": "USD",
      "status": "failed",
      "customer_data": {
        "name": "Juan Pérez",
        "email": "juan@ejemplo.com"
      },
      "created_at": "2025-12-04T10:29:45Z",
      "completed_at": "2025-12-04T10:30:00Z",
      "payment_method": "bank_transfer",
      "description": "Orden #1234"
    }
  }
}

payment_link.cancelled

Se envía cuando cancelas manualmente un payment link.

{
  "id": "wh_evt_550e8400-e29b-41d4-a716-446655440002",
  "event": "payment_link.cancelled",
  "created": "2025-12-04T11:00:00Z",
  "api_version": "2025-12-03",
  "source": "subscription",
  "data": {
    "object": {
      "id": "pl_uuid",
      "amount": 100.0,
      "currency": "USD",
      "status": "cancelled",
      "customer_data": {
        "name": "Juan Pérez",
        "email": "juan@ejemplo.com"
      },
      "created_at": "2025-12-04T10:00:00Z",
      "completed_at": "2025-12-04T11:00:00Z",
      "payment_method": "bank_transfer",
      "description": "Orden #1234"
    }
  }
}

payment_link.expired

Se envía cuando un payment link expira sin ser pagado.

{
  "id": "wh_evt_550e8400-e29b-41d4-a716-446655440003",
  "event": "payment_link.expired",
  "created": "2025-12-04T12:00:00Z",
  "api_version": "2025-12-03",
  "source": "subscription",
  "data": {
    "object": {
      "id": "pl_uuid",
      "amount": 100.0,
      "currency": "USD",
      "status": "expired",
      "customer_data": {
        "name": "Juan Pérez",
        "email": "juan@ejemplo.com"
      },
      "created_at": "2025-12-04T10:00:00Z",
      "completed_at": "2025-12-04T12:00:00Z",
      "payment_method": "bank_transfer",
      "description": "Orden #1234"
    }
  }
}

Eventos de Pagos con Tarjeta

card_payment.completed

Se envía cuando un cliente completa exitosamente un pago con tarjeta.

{
  "id": "wh_evt_661f9511-f30c-42e5-b827-557766551111",
  "event": "card_payment.completed",
  "created": "2026-03-20T14:35:00Z",
  "api_version": "2025-12-03",
  "source": "subscription",
  "data": {
    "object": {
      "id": "59294a0c-1c51-45e4-afa5-bafeac73d08f",
      "amount_usd": 100.50,
      "original_amount": 100.50,
      "original_currency": "USD",
      "status": "completed",
      "customer_name": "Juan Pérez",
      "customer_email": "juan@ejemplo.com",
      "description": "Factura #1234 - Servicio mensual",
      "created_at": "2026-03-20T10:00:00Z",
      "completed_at": "2026-03-20T14:35:00Z"
    }
  }
}

card_payment_link.cancelled

Se envía cuando cancelas manualmente un enlace de pago con tarjeta.

{
  "id": "wh_evt_883b1733-h52e-64g7-d049-779988773333",
  "event": "card_payment_link.cancelled",
  "created": "2026-03-20T15:10:00Z",
  "api_version": "2025-12-03",
  "source": "subscription",
  "data": {
    "object": {
      "id": "59294a0c-1c51-45e4-afa5-bafeac73d08f",
      "amount_usd": 100.50,
      "original_amount": 100.50,
      "original_currency": "USD",
      "status": "cancelled",
      "customer_name": "Juan Pérez",
      "customer_email": "juan@ejemplo.com",
      "description": "Factura #1234 - Servicio mensual",
      "created_at": "2026-03-20T10:00:00Z",
      "completed_at": null
    }
  }
}

Campos del Objeto de Datos (Pagos con Tarjeta)

Los campos disponibles en data.object para eventos de pagos con tarjeta:

Campo	Tipo	Descripción
`id`	string	ID único del pago con tarjeta
`amount_usd`	number	Monto en USD
`original_amount`	number	Monto original proporcionado
`original_currency`	string	Moneda original de la solicitud
`status`	string	Estado actual: `completed`, `cancelled`
`customer_name`	string	Nombre del cliente
`customer_email`	string	Email del cliente
`description`	string/null	Descripción del pago
`created_at`	string	Fecha de creación (ISO 8601)
`completed_at`	string/null	Fecha de completación (ISO 8601)

Campos del Objeto de Datos

Los campos disponibles en data.object son:

Campo	Tipo	Descripción
`id`	string	ID único del pago o payment link
`amount`	number	Monto del pago
`currency`	string	Código de moneda (ISO 4217)
`status`	string	Estado actual del recurso
`customer_data`	object	Datos del cliente (nombre, email)
`created_at`	string	Fecha de creación (ISO 8601)
`completed_at`	string	Fecha de finalización (ISO 8601)
`payment_method`	string	Método de pago utilizado
`description`	string	Descripción del pago (la que enviaste)

Objeto customer_data

Campo	Tipo	Descripción
`name`	string	Nombre del cliente (opcional)
`email`	string	Email del cliente (opcional)

Próximos Pasos

Verificación de Firma - Asegura tus webhooks
Mejores Prácticas - Recomendaciones para producción