Skip to main content

​
Qué son los webhooks

Los webhooks son notificaciones HTTP que VenePagos envía a tu servidor cuando ocurren eventos importantes, como un pago completado o una transferencia fallida.

​
Cómo funcionan

  1. Configuras una URL de tu servidor como endpoint de webhook
  2. Cuando ocurre un evento, VenePagos envía un POST a tu URL
  3. Tu servidor procesa la notificación y responde con 200 OK

​
Eventos disponibles

EventoDescripción
transaction.completedUna transacción se completó exitosamente
transaction.failedUna transacción falló
transaction.pendingUna transacción está en proceso
transfer.completedUna transferencia bancaria se completó
transfer.failedUna transferencia bancaria falló
merchant.updatedSe actualizó la configuración del merchant
invitation.acceptedUn miembro aceptó la invitación

​
Formato del payload

{
  "event": "transaction.completed",
  "timestamp": "2025-01-15T14:30:00Z",
  "data": {
    "id": "txn_abc123",
    "merchantId": "mch_xyz789",
    "type": "PAYMENT",
    "amount": 50.00,
    "status": "COMPLETED",
    "environment": "live"
  }
}

​
Implementar un webhook

app.post('/webhooks/venepagos', (req, res) => {
  const event = req.body;

  switch (event.event) {
    case 'transaction.completed':
      // Marcar orden como pagada
      console.log('Pago recibido:', event.data.id);
      break;
    case 'transaction.failed':
      // Notificar al usuario
      console.log('Pago fallido:', event.data.id);
      break;
  }

  res.status(200).json({ received: true });
});

​
Buenas prácticas

Tu endpoint debe responder en menos de 5 segundos. Si necesitas hacer procesamiento pesado, responde 200 inmediatamente y procesa en background.
Los webhooks pueden enviarse más de una vez. Usa el id de la transacción para verificar si ya procesaste el evento.
Tu endpoint de webhook debe usar HTTPS para proteger los datos en tránsito.
Los webhooks funcionan tanto en sandbox como en producción. Usa sandbox para probar tu implementación antes de ir a producción.