En esta página

Webhooks

Recibe notificaciones en tiempo real cuando ocurran eventos en tus órdenes de cobro.

¿Qué son los webhooks?

Los webhooks son notificaciones HTTP POST que iion pay envía a tu servidor cuando ocurre un evento importante, como cuando un pago se completa o falla. Esto te permite actualizar el estado de las órdenes en tu sistema de forma automática sin necesidad de consultar la API constantemente.

Configura tu webhook URL
Ve a Integraciones → Webhooks en el panel para configurar la URL donde recibirás las notificaciones.

Tipos de eventos

Evento Descripción
payment.completed El pago se completó exitosamente. La orden pasa a estado COMPLETED.
payment.failed El pago falló. La orden pasa a estado FAILED. Trae failureCode y failureReason (ver Payload de pago fallido).
payment.attempt_failed Cobro al entregar (Bre-B): el banco rechazó un intento de pago, pero la orden sigue en PENDING y se puede reintentar. Ver Cobrar al entregar.
payment.expired El cobro venció sin que nadie lo pagara. Solo llega con los webhooks V2 activos.
payment.cancelled El comercio canceló el cobro antes de que se pagara.
payment.confirmed El riel alcanzó la finalidad: ya puedes entregar.
payment.refunded Se devolvió el importe completo.
payment.partially_refunded Se devolvió una parte. El aviso trae refundedAmount y remainingAmount.
payment.chargeback El pagador reclamó el cargo a su banco.
payment.disputed El pago está en disputa.
payment.dispute_won Se ganó la disputa. El cobro vuelve a quedar a tu favor y no se devolvió dinero.
refund.requested El comercio pidió un reembolso.
refund.approved Un operador aprobó la solicitud. Todavía no se ha devuelto el dinero.
refund.rejected Un operador rechazó la solicitud.
refund.completed Quedó constancia de la devolución.
settlement.closed Se cerró la liquidación de un día (hora de Bogotá): lo cobrado, la comisión, lo que llegó a la wallet y lo devuelto ese día. No mueve dinero: el cobro ya se había acreditado. Ver Payload de liquidación.
bill.completed Un pago de factura o de convenio de recaudo que hizo tu comercio terminó bien. Ver Payload de recargas y facturas.
bill.failed Un pago de factura o de convenio de recaudo que hizo tu comercio falló.
topup.completed Una recarga, un paquete u otro producto que compró tu comercio terminó bien. Ver Payload de recargas y facturas.
topup.failed Una recarga, un paquete u otro producto que compró tu comercio falló.
escrow.held Cobro con custodia: el pago quedó retenido hasta que el comprador y tú confirmen la entrega.
escrow.confirmation Cobro con custodia: una de las dos partes confirmó la entrega. El aviso trae side, buyerConfirmed y merchantConfirmed.
escrow.disputed Cobro con custodia: una parte abrió una disputa. El aviso trae openedBy y reason.
escrow.released Cobro con custodia: el dinero retenido se liberó a tu favor.
escrow.refunded Cobro con custodia: el dinero retenido se devolvió al comprador.
test.ping Aviso de prueba que envías tú desde el panel o con POST /api/v1/collect/webhook/test para validar tu servidor y tu verificación de firma. Llega aunque tu lista de eventos no lo incluya. Trae data.test: true, data.status: "TEST" y data.amount: 0. Responde 2xx y no lo proceses como pago.

Los eventos no se habilitan cuenta por cuenta: la misma configuración aplica a todas las cuentas. Los avisos escrow.* solo llegan en cobros con custodia: su data trae el id del cobro y el status de la custodia, no la forma completa del cobro.

Puedes elegir qué eventos recibir desde el panel de negocios. Si no eliges ninguno, recibes todos. Si tienes dudas sobre los eventos, escribe a soporte@iionpay.com.

Un cobro completado todavía puede cambiar. Un reembolso o un contracargo llega como un evento NUEVO; el anterior nunca se edita. No des un cobro por cerrado solo porque recibiste payment.completed: si entregas mercancía, espera también payment.confirmed.

Estructura del webhook

Cada webhook incluye headers de seguridad y un payload JSON con los detalles del evento:

Headers

POST /tu-webhook-url HTTP/1.1
Host: tu-servidor.com
Content-Type: application/json
User-Agent: iion-pay-Webhook/1.0
X-IION-Signature: sha256=a1b2c3d4e5f6...
X-IION-Timestamp: 1705323600000
X-IION-Event-Id: 9b2f4c1e-3a7d-4f6b-8e21-5c0d9a7b3e14
X-IION-Event-Type: payment.completed
X-NIIO-Signature: sha256=a1b2c3d4e5f6...
X-NIIO-Timestamp: 1705323600000
X-NIIO-Event-Id: 9b2f4c1e-3a7d-4f6b-8e21-5c0d9a7b3e14
X-NIIO-Event-Type: payment.completed
Header Descripción
X-IION-Signature Firma HMAC-SHA256 del payload para verificar autenticidad
X-IION-Timestamp Timestamp en milisegundos de cuando se generó el webhook
X-IION-Event-Id Identificador único del aviso (UUID). Es el mismo valor que el campo id del payload. Úsalo para descartar reintentos repetidos.
X-IION-Event-Type Nombre del evento. Es el mismo valor que el campo event del payload.

También llegan como X-NIIO-* con el mismo valor, por compatibilidad.

Payload

{
  "id": "9b2f4c1e-3a7d-4f6b-8e21-5c0d9a7b3e14",
  "event": "payment.completed",
  "data": {
    "id": "4e7c2a91-8f3b-4d6e-a1c5-0b9d8e7f6a52",
    "reference": "ORDER-001",
    "amount": 50745,
    "baseAmount": 50000,
    "feeAmount": 745,
    "currency": "COP",
    "status": "COMPLETED",
    "paidAt": "2024-01-15T12:15:00.000Z",
    "metadata": {}
  },
  "timestamp": "2024-01-15T12:15:01.000Z"
}
¿Cuánto entró neto a tu cuenta?
baseAmount es el valor del cobro: el monto que pediste al crear la orden. amount es lo que pagó el pagador y feeAmount es la comisión. Con la comisión a cargo del comercio (por defecto), amount es igual a baseAmount y la comisión se descuenta de lo que recibes. Con la comisión a cargo del pagador, amount es baseAmount + feeAmount y recibes baseAmount. El ejemplo usa la comisión a cargo del pagador (Bre-B, plan START). En órdenes anteriores a 2026 estos campos pueden venir null. En los cobros en bolívares, estos montos van en Bs. Ver Cobros en bolívares.

Cobros en bolívares (Venezuela)

En un cobro en bolívares, currency es "VES". Los campos amount, baseAmount y feeAmount van en Bs. La forma del payload no cambia. El webhook no informa los pesos acreditados a tu saldo.

Payload de pago fallido

{
  "id": "1c8e5d3a-6b2f-4a9e-9d74-3f0a2b8c6e15",
  "event": "payment.failed",
  "data": {
    "id": "4e7c2a91-8f3b-4d6e-a1c5-0b9d8e7f6a52",
    "reference": "ORDER-001",
    "amount": 50745,
    "baseAmount": 50000,
    "feeAmount": 745,
    "currency": "COP",
    "status": "FAILED",
    "paidAt": null,
    "metadata": {},
    "failureCode": "R000",
    "failureReason": "El banco del pagador rechazó el pago sin indicar el motivo."
  },
  "timestamp": "2024-01-15T12:15:01.000Z"
}

El id de primer nivel identifica el aviso y no cambia entre reintentos. El data.id es el id del cobro. Los dos son UUID.

failureCode es el código del proveedor (por ejemplo R000), o null si no llegó código. failureReason es un texto en español, nunca vacío. Un código sin texto propio recibe el motivo genérico «El pago no se pudo completar.». Los dos campos son nuevos en payment.failed. Si validas el cuerpo de forma estricta, acepta campos adicionales.

Payload de intento fallido (cobrar al entregar)

En un cobro de entrega (deliveryMode: true), un rechazo del banco no cierra la orden. La orden sigue en PENDING y llega payment.attempt_failed. El vencimiento de la solicitud de 10 minutos no genera este evento.

{
  "id": "7d2f9b10-3c4e-4a58-b6e1-9a0c5d4e3f21",
  "event": "payment.attempt_failed",
  "data": {
    "id": "4e7c2a91-8f3b-4d6e-a1c5-0b9d8e7f6a52",
    "reference": "PEDIDO-1042",
    "amount": 45000,
    "baseAmount": 45000,
    "feeAmount": 0,
    "currency": "COP",
    "status": "PENDING",
    "paidAt": null,
    "metadata": {},
    "failureCode": "R000",
    "failureReason": "El banco del pagador rechazó el pago sin indicar el motivo.",
    "attempt": 1
  },
  "timestamp": "2026-11-04T12:15:01.000Z"
}

attempt es el número del intento que falló. failureCode y failureReason tienen el mismo significado que en payment.failed. El pedido se da por pagado solo con payment.completed.

Payload de liquidación

{
  "id": "7d1a9e4b-2c6f-4b8a-b3e0-6f5c1d2a9e87",
  "event": "settlement.closed",
  "data": {
    "settlementId": "a3f6b2d8-1e4c-4f9a-8b7d-2c5e0f1a6d34",
    "periodKey": "2024-01-15",
    "periodStart": "2024-01-15T05:00:00.000Z",
    "periodEnd": "2024-01-16T05:00:00.000Z",
    "currency": "COP",
    "destinationKind": "MERCHANT",
    "grossAmount": 150000,
    "feeAmount": 2235,
    "taxAmount": 0,
    "netAmount": 147765,
    "refundedAmount": 0,
    "orderCount": 3,
    "status": "CLOSED"
  },
  "timestamp": "2024-01-16T05:20:01.000Z"
}

Siempre se cumple grossAmount = netAmount + feeAmount + taxAmount. destinationKind indica a qué wallet llegó el dinero: MERCHANT (la cuenta de negocio) u OWNER (la wallet personal del dueño).

Payload de recargas y facturas

Los eventos bill.* y topup.* avisan del resultado de una compra que hizo tu comercio. bill.* cubre los productos collection (facturas y convenios de recaudo) y sportbet. topup.* cubre cualquier otro productType, por ejemplo recharge o package.

{
  "id": "5f3b8d2a-9c1e-4a7f-b6d0-2e8a4c1f7b93",
  "event": "bill.completed",
  "data": {
    "id": "c2a7e4f1-6d3b-4e8a-9f15-7b0c3d2e1a68",
    "status": "completed",
    "productType": "collection",
    "amountCop": 85000,
    "feeCop": 0,
    "totalCop": 85000,
    "reference": "mf2k9x1a03bz",
    "ticket": null,
    "createdAt": "2024-01-15T14:02:10.000Z",
    "completedAt": "2024-01-15T14:02:14.000Z"
  },
  "timestamp": "2024-01-15T14:02:15.000Z"
}
  • data.id es el id de la compra (UUID).
  • status es completed en *.completed y failed en *.failed.
  • amountCop, feeCop y totalCop son números en pesos. Siempre se cumple totalCop = amountCop + feeCop.
  • reference es el código de trazabilidad de la compra (texto).
  • ticket es el comprobante del proveedor (objeto) o null. Su forma depende del proveedor.
  • completedAt puede llegar en null.

Verificar la firma

¡Siempre verifica la firma!
Antes de procesar cualquier webhook, verifica que la firma sea válida para asegurarte de que proviene de iion pay y no ha sido alterado.

La firma se calcula usando HMAC-SHA256 con tu webhook secret y la concatenación del timestamp y el payload:

signature = HMAC-SHA256(webhook_secret, timestamp + "." + payload)

Ejemplos de verificación

const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, timestamp, webhookSecret) {
  // Verificar que el timestamp no sea muy antiguo (5 minutos)
  const currentTime = Date.now();
  const webhookTime = parseInt(timestamp, 10);

  if (currentTime - webhookTime > 5 * 60 * 1000) {
    throw new Error('Webhook timestamp too old');
  }

  // Calcular la firma esperada
  const signedPayload = `${timestamp}.${payload}`;
  const expectedSignature = crypto
    .createHmac('sha256', webhookSecret)
    .update(signedPayload)
    .digest('hex');

  // Comparar firmas de forma segura
  const receivedSig = signature.replace('sha256=', '');
  const expectedBuf = Buffer.from(expectedSignature);
  const receivedBuf = Buffer.from(receivedSig);

  // timingSafeEqual lanza error si las longitudes difieren
  if (
    expectedBuf.length !== receivedBuf.length ||
    !crypto.timingSafeEqual(expectedBuf, receivedBuf)
  ) {
    throw new Error('Invalid webhook signature');
  }

  return true;
}

// Uso en Express
app.post('/webhook', express.raw({ type: 'application/json' }), async (req, res) => {
  const signature = req.headers['x-iion-signature'];
  const timestamp = req.headers['x-iion-timestamp'];
  const payload = req.body.toString();

  try {
    verifyWebhookSignature(payload, signature, timestamp, process.env.WEBHOOK_SECRET);

    const event = JSON.parse(payload);

    // Procesar el evento
    switch (event.event) {
      case 'payment.completed':
        // Marcar orden como pagada en tu sistema
        await markOrderAsPaid(event.data.id, event.data.reference);
        break;
      case 'payment.failed':
        // Manejar fallo - notificar al usuario, etc.
        await handlePaymentFailure(event.data.id, event.data.reference);
        break;
    }

    res.status(200).send('OK');
  } catch (error) {
    console.error('Webhook error:', error.message);
    res.status(400).send('Invalid signature');
  }
});
import os
import hmac
import hashlib
import time
import json
from flask import Flask, request

app = Flask(__name__)

def verify_webhook_signature(payload, signature, timestamp, webhook_secret):
    # Verificar que el timestamp no sea muy antiguo (5 minutos)
    current_time = int(time.time() * 1000)
    webhook_time = int(timestamp)

    if current_time - webhook_time > 5 * 60 * 1000:
        raise ValueError('Webhook timestamp too old')

    # Calcular la firma esperada
    signed_payload = f"{timestamp}.{payload}"
    expected_signature = hmac.new(
        webhook_secret.encode(),
        signed_payload.encode(),
        hashlib.sha256
    ).hexdigest()

    # Comparar firmas
    received_sig = signature.replace('sha256=', '')

    if not hmac.compare_digest(expected_signature, received_sig):
        raise ValueError('Invalid webhook signature')

    return True

@app.route('/webhook', methods=['POST'])
def webhook():
    signature = request.headers.get('X-IION-Signature')
    timestamp = request.headers.get('X-IION-Timestamp')
    payload = request.get_data(as_text=True)

    try:
        verify_webhook_signature(
            payload,
            signature,
            timestamp,
            os.environ['WEBHOOK_SECRET']
        )

        event = json.loads(payload)

        # Procesar el evento
        if event['event'] == 'payment.completed':
            # Marcar orden como pagada en tu sistema
            mark_order_as_paid(event['data']['id'], event['data']['reference'])
        elif event['event'] == 'payment.failed':
            # Manejar fallo - notificar al usuario, etc.
            handle_payment_failure(event['data']['id'], event['data']['reference'])

        return 'OK', 200
    except ValueError as e:
        return str(e), 400
function verifyWebhookSignature($payload, $signature, $timestamp, $webhookSecret) {
    // Verificar que el timestamp no sea muy antiguo (5 minutos)
    $currentTime = round(microtime(true) * 1000);
    $webhookTime = intval($timestamp);

    if ($currentTime - $webhookTime > 5 * 60 * 1000) {
        throw new Exception('Webhook timestamp too old');
    }

    // Calcular la firma esperada
    $signedPayload = $timestamp . '.' . $payload;
    $expectedSignature = hash_hmac('sha256', $signedPayload, $webhookSecret);

    // Comparar firmas
    $receivedSig = str_replace('sha256=', '', $signature);

    if (!hash_equals($expectedSignature, $receivedSig)) {
        throw new Exception('Invalid webhook signature');
    }

    return true;
}

// Uso
$payload = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_IION_SIGNATURE'] ?? '';
$timestamp = $_SERVER['HTTP_X_IION_TIMESTAMP'] ?? '';

try {
    verifyWebhookSignature($payload, $signature, $timestamp, getenv('WEBHOOK_SECRET'));

    $event = json_decode($payload, true);

    // Procesar el evento
    switch ($event['event']) {
        case 'payment.completed':
            // Marcar orden como pagada en tu sistema
            markOrderAsPaid($event['data']['id'], $event['data']['reference']);
            break;
        case 'payment.failed':
            // Manejar fallo - notificar al usuario, etc.
            handlePaymentFailure($event['data']['id'], $event['data']['reference']);
            break;
    }

    http_response_code(200);
    echo 'OK';
} catch (Exception $e) {
    http_response_code(400);
    echo $e->getMessage();
}

Webhook general vs. webhook por API key

Tu comercio tiene un Webhook general: una URL, una lista de eventos y un secreto de firma. Además, cada API key puede tener su propio webhook. El webhook de una llave tiene una URL https:// pública, una lista de eventos (si la lista está vacía, recibe todos) y un secreto de firma propio con formato whsec_…. Ese secreto es distinto del secreto del Webhook general.

Disponible de forma gradual
Disponible de forma gradual. La función se activa por negocio. Si en la página de tu llave ves el aviso «Los avisos de esta llave van al Webhook general.», tus avisos van al Webhook general.

A qué destino llega cada aviso

Cada aviso llega a un solo destino, nunca a los dos.

Caso URL de destino Secreto de firma
Cobro creado por la API con una llave que tiene webhook propio La URL de esa llave El secreto de esa llave
Cobro creado por la API con una llave sin webhook propio La URL del Webhook general El secreto del Webhook general
Cobro sin llave (link, tienda, botón o panel) La URL del Webhook general El secreto del Webhook general
Cobro anterior a esta función La URL del Webhook general El secreto del Webhook general
Cobro de una llave revocada que tenía webhook propio La URL de esa llave El secreto de esa llave
Evento sin cobro, por ejemplo settlement.closed La URL del Webhook general El secreto del Webhook general

iion pay decide el destino en cada evento. Usa la configuración actual de la llave que creó el cobro, no la del momento de crear el cobro. Si agregas una URL a la llave, los eventos siguientes de sus cobros van a esa URL. Los reintentos de un aviso ya enviado van a la misma URL de ese aviso.

Cómo validar la firma

La firma no cambia de formato. Es el HMAC-SHA256 de ${timestamp}.${body} y llega en las mismas cabeceras de siempre. Solo cambia el secreto que se usa.

  • Valida cada aviso con el secreto del destino que configuraste: el de la llave si llegó a la URL de la llave, el general si llegó a la URL general.

Dónde se configura

  1. Abre API keys en el panel y entra a la llave.
  2. En la sección Webhook, define la URL y los eventos.
  3. Usa Probar para enviar un aviso de prueba.
  4. Consulta o regenera el secreto de la llave.
  5. Usa Quitar para borrar el webhook propio. La llave vuelve a usar el Webhook general.

La pantalla del webhook del comercio se llama ahora Webhook general.

Regenerar el secreto de una llave
Los reintentos pendientes salen firmados con el secreto nuevo. Copia el secreto nuevo en tu servidor apenas lo regeneres: hasta que lo hagas, esos avisos no pasarán tu validación de firma. Hazlo en un momento de poco tráfico.

Política de reintentos

Tu servidor tiene 10 segundos para responder con un código 2xx. Si no responde a tiempo o responde con otro código, iion pay reintenta el webhook con este calendario:

Intento Cuándo se envía
1 Inmediato
2 5 minutos después del intento 1
3 30 minutos después del intento 2
4 2 horas después del intento 3
5 24 horas después del intento 4

Los tiempos son aproximados: los reintentos pendientes se revisan cada minuto. Después del intento 5 fallido, el webhook queda marcado como fallido y no se reintenta más. Puedes ver el historial de webhooks en el dashboard.

Buenas prácticas

  • Responde rápido: Responde con 200 OK tan pronto verifiques la firma. Procesa la lógica de negocio de forma asíncrona.
  • Idempotencia: Tu endpoint debe manejar el mismo evento múltiples veces sin efectos secundarios.
  • Verifica siempre: Nunca proceses un webhook sin verificar la firma.
  • Usa HTTPS: Tu endpoint webhook debe usar HTTPS para proteger los datos en tránsito.
  • Logging: Registra todos los webhooks recibidos para debugging y auditoría.

Registrar tu webhook por API

Una llave con el permiso collect:webhook registra su propio webhook. El permiso se otorga al crear la llave desde la tarjeta «Deja que tu agente integre iion pay» de Integraciones en el panel, o en los permisos de la llave.

PUT /api/v1/collect/webhook
X-Api-Key: niio_live_...
X-Api-Secret: niio_secret_...

{ "url": "https://tu-dominio.com/webhooks/iionpay", "events": ["payment.completed"] }
  • url es obligatoria: es el campo de la URL en este PUT. Debe ser https y pública.
  • El PUT responde 200.
  • events es opcional. Una lista vacía [] = todos los eventos. Si lo omites, los eventos guardados no cambian (en el primer registro: todos).
  • La respuesta trae url, events y secret (whsec_...). El secreto llega solo en la respuesta que lo crea (el primer PUT). Un PUT posterior devuelve secret: null y conserva el mismo secreto; si lo perdiste, regenéralo en el panel. Valida la firma con ese whsec_.
  • GET /api/v1/collect/webhook devuelve url y events, sin el secreto.
  • POST /api/v1/collect/webhook/test envía un aviso de prueba firmado (evento test.ping). Responde 201 con logId, url, delivered, responseStatus, responseBody y attempts; delivered: true = tu servidor respondió 2xx. Responde 400 si la llave no tiene URL y 429 WEBHOOK_TEST_RATE_LIMITED con más de 5 pruebas por minuto por comercio.
  • El aviso test.ping llega aunque events de la llave no lo incluya. Se envía una sola vez, sin reintentos, con la misma firma que un aviso real. Su data trae test: true, status: "TEST", amount: 0, baseAmount: 0, feeAmount: 0 y una reference con el prefijo TEST-. Ningún pago ocurrió: tu handler debe verificar la firma y responder 2xx, sin procesarlo como pago ni actualizar pedidos.
  • Errores: 403 API_KEY_PERMISSION_DENIED sin el permiso; 400 si la URL no es https o no es pública; 403 FEATURE_DISABLED si el webhook por llave no está habilitado (configura el webhook general del comercio en el panel, en Integraciones → Webhooks («Webhook general»), y copia ahí la «Clave del webhook» como IIONPAY_WEBHOOK_SECRET).

Regenerar el webhook secret

Si sospechas que tu webhook secret ha sido comprometido, puedes regenerarlo desde el dashboard:

  1. Ve a Integraciones → Webhooks en el panel
  2. Haz clic en "Regenerar Secret"
  3. Actualiza tu servidor con el nuevo secret
Actualiza tu servidor primero
Al regenerar el secret, los webhooks con la firma anterior serán rechazados. Asegúrate de actualizar tu servidor con el nuevo secret antes de regenerarlo, o hazlo durante un período de bajo tráfico.