Webhooks

Los webhooks te permiten recibir notificaciones en tiempo real sobre eventos importantes en tu cuenta. Cuando ocurre un evento, nuestro sistema enviará una solicitud HTTP POST a la URL que hayas configurado.

Configuración

1. Ingresa al panel administrativo de tu cuenta de Vesvank y navega a la sección Webhooks en el menú lateral.
2. Haz clic en en el botón Configurar.
3. Ingresa la URL a la que deseas que lleguen los eventos. Esta URL debe aceptar solicitudes HTTP POST.
4. Activa el webhook usando el interruptor o botón de Habilitar.
5. Una vez habilitado, se mostrará el Webhook Secret. Este secreto es fundamental para verificar la autenticidad de las firmas de los webhooks que recibas.

Resumen de eventos

Evento	Descripción
payment_request.paid	Enviado cuando una solicitud de pago se marca como pagada

Seguridad

Verificación de Firma

Cada solicitud webhook incluye una firma HMAC-SHA256 en el encabezado X-Webhook-Signature. Debes verificar esta firma para asegurarte de que la solicitud proviene exclusivamente de Vesvank.

Importante

Asegúrate de usar el cuerpo crudo de la solicitud (raw body) para calcular la firma. Si usas middleware como body-parser en Node.js o express.json() en Express, captura el raw body antes de procesarlo. Usar el body ya parseado puede invalidar la verificación de la firma.

JavaScript/Node.js

// Ejemplo de verificación en JavaScript/Node.js
const crypto = require('crypto');

function verifySignature(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(JSON.stringify(payload))
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signature)
  );
}

// Ejemplo de uso en Express.js
app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['x-webhook-signature'];
  const rawBody = req.body; // Buffer
  if (!verifySignature(rawBody, signature, process.env.WEBHOOK_SECRET)) {
    return res.status(401).json({ error: 'Invalid signature' });
  }
  // Procesar el webhook...
  res.status(200).json({ received: true });
});

PHP

// Ejemplo de verificación en PHP
function verify_signature($payload, $signature, $secret) {
  $expected = hash_hmac('sha256', $payload, $secret);
  return hash_equals($expected, $signature);
}

// Ejemplo de uso
$payload = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'];
$secret = getenv('WEBHOOK_SECRET');

if (!verify_signature($payload, $signature, $secret)) {
  http_response_code(401);
  echo json_encode(['error' => 'Invalid signature']);
  exit;
}

// Procesar el webhook...
http_response_code(200);
echo json_encode(['received' => true]);

Ruby

# Ejemplo de verificación en Ruby
def verify_signature(payload, signature, secret)
  expected = OpenSSL::HMAC.hexdigest("SHA256", secret, payload)
  ActiveSupport::SecurityUtils.secure_compare(expected, signature)
end

Manejo de Errores

Política de Reintentos

• Los webhooks fallidos se reintentarán automáticamente hasta 3 veces
• El intervalo entre reintentos es de 5 minutos
• Después de 3 intentos fallidos, el evento se marcará como fallido permanentemente

Mejores Prácticas

• Responde con un código de estado 200 lo más rápido posible
• Procesa los eventos de forma asíncrona en tu servidor
• Mantén un registro de los eventos recibidos
• Implementa manejo de errores robusto
• Verifica siempre la firma del webhook

Ambiente de pruebas

Puedes configurar una URL de prueba en tu cuenta con eventos simulados. Para facilitar el desarrollo y pruebas locales, recomendamos exponer tu servidor local usando ngrok u otra herramienta similar. Así podrás recibir webhooks en tu entorno de desarrollo sin exponer tu infraestructura real.