¿Qué es un Webhook?
Un webhook es una notificación HTTP POST que OnePay envía a tu servidor cuando ocurre un evento relevante (pago aprobado, cargo exitoso, dispersión procesada, etc.). En lugar de consultar la API constantemente, tu sistema recibe la información automáticamente.Ejemplo Rápido
Cuando ocurre un evento, OnePay envía una solicitud POST a tu endpoint con este formato:¿Por qué usar Webhooks?
| Sin webhooks | Con webhooks |
|---|---|
| Tu sistema consulta la API cada X segundos | OnePay notifica a tu sistema al instante |
| Mayor consumo de recursos y requests | Solo procesas cuando hay un evento real |
| Posible retraso en detectar cambios | Actualización en tiempo real |
Configuración
1. Crear un endpoint público
Tu servidor debe exponer un endpoint HTTPS que reciba solicitudes POST. Ejemplo:2. Registrar el webhook en OnePay
Puedes configurar tus webhooks de dos maneras: Opción A: Mediante el administrador webAdministrar webhooks
Listar webhooks
Obtén todos tus webhooks configurados
Ver webhook
Consulta detalles y auditoría de un webhook
Crear webhook
Crea un nuevo webhook mediante la API
Actualizar webhook
Modifica la configuración de un webhook
Eliminar webhook
Elimina un webhook existente
3. Verificar la firma HMAC-SHA256
Cada webhook incluye una firma HMAC-SHA256 en el headerx-signature para verificar que proviene de OnePay. Debes validar esta firma antes de procesar el evento.
- JavaScript (Node.js)
- Python (Flask)
- PHP
HMAC es un hash con clave, no un cifrado. No se puede “descifrar”, solo se puede comparar calculando el mismo hash con los mismos datos y la misma clave.
4. Verificar el header de autenticación
Cada solicitud incluye un headerx-webhook-token con un token de autorización. Este token es diferente al webhook secret y también sirve para verificar el origen:
Eventos disponibles
Los tipos de webhook que puedes recibir se documentan en cada sección:| Recurso | Eventos | Cuándo se dispara | Documentación |
|---|---|---|---|
| Payments | payment.approved | El cliente completó el pago exitosamente | Ver detalles |
payment.declined | El pago fue rechazado | Ver detalles | |
payment.cancelled | El cliente canceló el pago | Ver detalles | |
| Charges | charge.succeeded | El cargo automático se procesó exitosamente | Ver detalles |
charge.declined | El cargo automático fue rechazado | Ver detalles | |
| Cashouts | cashout.processed | La dispersión se completó exitosamente | Ver detalles |
cashout.failed | La dispersión falló | Ver detalles | |
| Subscriptions | subscription.activated | La suscripción se activó | Ver detalles |
subscription.cancelled | La suscripción fue cancelada | Ver detalles | |
subscription.payment_failed | Falló el cobro de una cuota | Ver detalles | |
| Accounts | account.active | La cuenta bancaria fue validada | Ver detalles |
account.rejected | La cuenta fue rechazada | Ver detalles |
Testing local
Para desarrollo local, usa Ngrok para exponer tu servidor:https://abc123.ngrok.io) que puedes registrar como webhook.
Buenas prácticas
- Responde con HTTP
200lo antes posible para evitar reintentos - Procesa los eventos de forma asíncrona (usa una cola de trabajo)
- Verifica siempre la firma HMAC antes de procesar el evento
- Implementa idempotencia para manejar eventos duplicados
- Registra los eventos recibidos para depuración