Skip to main content
Los webhooks te permiten recibir notificaciones HTTP automáticas cuando ocurren eventos en tu cuenta (pagos aprobados, dispersiones procesadas, cargos fallidos, etc.), sin necesidad de consultar la API constantemente.

​
¿Cómo funcionan?

1

Registra una URL

Crea un webhook con la URL de tu servidor y los eventos que quieres escuchar.
2

OnePay envía el evento

Cada vez que ocurra un evento seleccionado, OnePay enviará un POST a tu URL con el payload del evento en formato JSON.
3

Responde con 200

Tu servidor debe responder con un código HTTP 200 en menos de 30 segundos. Si no, OnePay reintentará la entrega.
4

Verifica la firma

Valida el header x-onepay-signature con tu secret para asegurarte de que la petición proviene de OnePay.

​
Verificación de firma

Cada webhook incluye el header x-onepay-signature con un HMAC-SHA256 del body usando tu secret. Así puedes verificar que el evento es auténtico:
JavaScript
const crypto = require('crypto');

function verifySignature(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}
Python
import hmac
import hashlib

def verify_signature(payload: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode(),
        payload,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(signature, expected)
Guarda tu secret de forma segura. Solo se muestra una vez al crear el webhook. Si lo pierdes, deberás eliminarlo y crear uno nuevo.

​
Eventos disponibles

​
Pagos

EventoDescripción
payment.createdPago creado
payment.approvedPago aprobado
payment.rejectedPago rechazado
payment.refundedPago devuelto
payment.expiredPago expirado
payment.partially_paidPago parcialmente completado
payment.partial_expiredPago parcial expirado
payment.issueIncidencia en el pago
payment.disputedPago disputado
payment.message.deliveredMensaje de pago entregado
payment.message.failedMensaje de pago fallido
payment.message.repliedMensaje de pago con respuesta
payment.deletedPago eliminado

​
Cargos

EventoDescripción
charge.createdCargo creado
charge.processingCargo en procesamiento
charge.paidCargo pagado exitosamente
charge.failedCargo fallido
charge.refundedCargo devuelto
charge.disputedCargo disputado

​
Dispersiones

EventoDescripción
cashout.createdDispersión creada
cashout.processingDispersión en procesamiento
cashout.completedDispersión completada
cashout.rejectedDispersión rechazada
cashout.cancelledDispersión cancelada
cashout.require_approvalDispersión requiere aprobación
cashout.turbo_onboardingOnboarding de dispersión turbo

​
Suscripciones

EventoDescripción
subscription.createdSuscripción creada
subscription.activeSuscripción activada
subscription.paidCuota de suscripción pagada
subscription.pass_dueSuscripción vencida
subscription.unpaidSuscripción sin pagar
subscription.canceledSuscripción cancelada
subscription.finishedSuscripción finalizada
subscription.frozenSuscripción congelada

​
Cuentas bancarias

EventoDescripción
account.pendingCuenta pendiente de validación
account.connectedCuenta conectada exitosamente
account.disconnectedCuenta desconectada
account.validatedCuenta validada
account.uncompletedCuenta incompleta

​
Otros

EventoDescripción
invoice.createdFactura creada
invoice.paidFactura pagada
invoice.canceledFactura cancelada
utility.paidPago de servicio público aprobado
utility.rejectedPago de servicio público rechazado
connect_link.completedLink de conexión completado
balance.updatedSaldo actualizado
wallet.transaction.createdTransacción de wallet creada

​
Endpoints

Listar webhooks

Consulta todos los webhooks registrados en tu cuenta.

Ver webhook

Obtén el detalle de un webhook específico.

Crear webhook

Registra una nueva URL y selecciona los eventos a escuchar.

Actualizar webhook

Modifica la URL, nombre o eventos de un webhook existente.

Eliminar webhook

Elimina un webhook de tu cuenta.

Ejemplos de payloads

Revisa la estructura de cada evento que recibirás.