Configurar webhooks

¿Qué son los webhooks?

Cuando ocurre un evento en una transacción, Rivopay envía un POST a tu webhookUrl registrada con los datos del evento.

Configurar tu webhookUrl

En la plataforma de cliente podrá configurar su propio webhookUrl en donde recibir los webhooks.

Headers del webhook

Header	Ejemplo	Descripción
Content-Type	application/json	Siempre JSON.
X-Webhook-Event	payin.completed	Tipo de evento.
X-Webhook-Timestamp	2026-07-22T15:04:05.123Z	ISO-8601 UTC con milisegundos. El del primer envío, no el de cada reintento. Parte del string firmado.
X-Webhook-Signature	sha256=9f86d0...	Firma HMAC-SHA256 en hex, con prefijo sha256=.
User-Agent	PaymentGateway-Webhook/1.0	Identificador del emisor.

Compatibilidad

Si aún no registraste una Clave para ese proveedor, el webhook llega sin X-Webhook-Signature ni X-Webhook-Timestamp. Una vez registrada la Clave, ambos headers vienen siempre.

No hay fallback: no se firma con la Clave de otro proveedor ni con ninguna clave por defecto. Por eso, una vez configurada tu Clave, rechaza todo webhook que llegue sin firma — la ausencia de los headers no es una excepción válida, es un webhook que no salió de nosotros.

Eventos disponibles

Evento	Header X-Webhook-Event	Cuándo se dispara
payin.completed	payin.completed	Cobro recibido y confirmado
payin.failed	payin.failed	Cobro rechazado o fallido
payin.reversed	payin.reversed	Cobro recibido fue devuelto al pagador (Nequi)
payout.completed	payout.completed	Dispersión enviada y confirmada
payout.failed	payout.failed	Dispersión rechazada por el proveedor
payout.reversed	payout.reversed	Dispersión fue revertida (Nequi)
payin.expired	payin.expired	El cobro venció sin pago (QR/push expirado)
payout.expired	payout.expired	La transferencia venció sin confirmación del proveedor

Colombia

Los mismos eventos aplican para Nequi y Bre-B (/v1/co/*), con montos en pesos COP. Ver Webhooks Nequi y Webhooks Bre-B. En sandbox los webhooks simulados incluyen el campo "sandbox": true.

Verificación de firma (HMAC-SHA256)

Cada webhook que Rivopay envía va firmado con HMAC-SHA256 usando la Clave que registraste. Recalcula la firma con tu misma Clave para confirmar que el webhook viene de Rivopay y que el cuerpo no fue alterado.

Formato de la Clave

La Clave se usa literalmente — no la decodifiques

La Clave entra al HMAC tal cual la registraste, como texto, con sus bytes UTF-8. La entregamos con pinta de hexadecimal (64 caracteres 0-9a-f), pero eso es solo el formato con que la generamos: es el texto lo que firma, no los bytes que ese hex representaría.

Con la Clave 4f3c9ab2...e701:

clave usada = "4f3c9ab2...e701"          → 64 bytes (el texto)   ✅ la firma coincide
clave usada = hex_decode("4f3c9ab2…")    → 32 bytes (decodificado) ❌ nunca coincide

Es el tropiezo más común al integrar: el valor parece hex, así que decodificarlo es el primer intento natural — y da una firma que no valida contra ningún webhook.

Cómo se calcula la firma

string_to_sign = `${X-Webhook-Timestamp}\n${raw_body}`
firma          = HMAC_SHA256(clave, string_to_sign)   // hex minúsculas
X-Webhook-Signature = "sha256=" + firma

• raw_body = el cuerpo HTTP crudo, byte a byte, tal como llega. No re-serializar el JSON antes de firmar (un JSON.parse + JSON.stringify puede cambiar orden/espacios y romper la firma).
• Separador = un salto de línea \n (LF, 0x0A) entre timestamp y body.
• La firma es hex en minúsculas.

Pasos de verificación (obligatorios)

1. Leer el cuerpo crudo del request (no el parseado).
2. Recomputar expected = "sha256=" + HMAC_SHA256(clave, timestamp + "\n" + raw_body).
3. Comparar expected con X-Webhook-Signature en tiempo constante (timingSafeEqual / hash_equals). No usar ==.
4. Validar la ventana temporal: rechazar si |now − X-Webhook-Timestamp| > 5 min (anti-replay).
5. (Recomendado) Deduplicar por txId: los reintentos reenvían el mismo payload, firma y timestamp.
6. Responder 2xx si se acepta. Cualquier no-2xx (o timeout) dispara reintentos.

Qué Clave usar (por proveedor)

La Clave se configura por región y proveedor — regions.CO.webhookSecrets.NEQUI y regions.CO.webhookSecrets.BREB, cada una independiente. Se solicitan al equipo de Rivopay durante el onboarding. El payload no incluye el proveedor, así que:

• Recomendado: configurar una URL de webhook por proveedor (webhookUrls). Cada endpoint recibe solo su proveedor → usa su Clave.
• Si usas una sola URL para todos los proveedores, registra la misma Clave para todos.

Ejemplos

Node.js (Express, raw body)

const crypto = require('crypto');
// Importante: capturar el body CRUDO
app.use('/webhooks', express.raw({ type: 'application/json' }));

app.post('/webhooks', (req, res) => {
  const secret    = process.env.RIVOPAY_WEBHOOK_SECRET; // la Clave tal cual, SIN hex_decode
  const signature = req.header('X-Webhook-Signature') || '';
  const timestamp = req.header('X-Webhook-Timestamp') || '';
  const rawBody   = req.body;                            // Buffer crudo

  // 1. Ventana temporal (±5 min)
  if (Math.abs(Date.now() - Date.parse(timestamp)) > 5 * 60 * 1000) {
    return res.status(401).send('stale timestamp');
  }
  // 2. Recomputar firma
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(`${timestamp}\n${rawBody.toString('utf8')}`)
    .digest('hex');
  // 3. Comparación en tiempo constante
  const ok = signature.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
  if (!ok) return res.status(401).send('bad signature');

  const event = JSON.parse(rawBody.toString('utf8'));
  // ... procesar (idempotente por event.txId) ...
  res.sendStatus(200);
});

PHP

$secret    = getenv('RIVOPAY_WEBHOOK_SECRET'); // la Clave tal cual, SIN hex2bin()
$signature = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'] ?? '';
$timestamp = $_SERVER['HTTP_X_WEBHOOK_TIMESTAMP'] ?? '';
$rawBody   = file_get_contents('php://input');

if (abs(time() - strtotime($timestamp)) > 300) {
    http_response_code(401); exit('stale timestamp');
}
$expected = 'sha256=' . hash_hmac('sha256', $timestamp . "\n" . $rawBody, $secret);
if (!hash_equals($expected, $signature)) {
    http_response_code(401); exit('bad signature');
}
$event = json_decode($rawBody, true);
// ... procesar idempotente por $event['txId'] ...
http_response_code(200);

Python (Flask)

import hmac, hashlib, os
from datetime import datetime, timezone
from flask import request, abort

def verify():
    secret    = os.environ['RIVOPAY_WEBHOOK_SECRET'].encode()  # .encode(), NO bytes.fromhex()
    signature = request.headers.get('X-Webhook-Signature', '')
    timestamp = request.headers.get('X-Webhook-Timestamp', '')
    raw_body  = request.get_data()  # bytes crudos

    ts = datetime.fromisoformat(timestamp.replace('Z', '+00:00'))
    if abs((datetime.now(timezone.utc) - ts).total_seconds()) > 300:
        abort(401)

    msg = timestamp.encode() + b'\n' + raw_body
    expected = 'sha256=' + hmac.new(secret, msg, hashlib.sha256).hexdigest()
    if not hmac.compare_digest(expected, signature):
        abort(401)
    # ... procesar idempotente por txId ...

Errores comunes

• Hacer hex_decode de la Clave antes de firmar → firma no coincide. Va tal cual, como cadena UTF-8.
• Firmar el body re-serializado en vez del crudo → firma no coincide. Usa los bytes tal cual llegan.
• Comparar con == en vez de timingSafeEqual / hash_equals.
• Olvidar el \n entre timestamp y body.
• No validar la ventana temporal → vulnerable a replay.
• Usar la Clave de otro proveedor cuando se comparte una sola URL.

Ejemplo de endpoint

El ejemplo mínimo de abajo usa express.json() por simplicidad. En producción, verifica la firma con el body crudo como se muestra arriba antes de confiar en el payload.

app.post('/webhook/rivopay', express.json(), async (req, res) => {
  const eventType = req.headers['x-webhook-event'];
  const payload = req.body;
  const { txId, status } = payload;

  switch (eventType) {
    case 'payin.completed':
      await confirmarPedido(txId, payload.netAmount);
      break;
    case 'payin.failed':
      await cancelarPedido(txId);
      break;
    case 'payout.failed':
      await notificarFalloPago(txId, payload.failureReason);
      break;
    case 'payout.reversed':
      await procesarReversion(txId);
      break;
  }

  // SIEMPRE responde 200 aunque tengas un error interno
  res.status(200).json({ received: true });
});

Importante

Tu endpoint debe responder en menos de 10 segundos y siempre devolver 200. Procesa la lógica de negocio de forma asíncrona si es necesario.