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.
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"
}
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.ides el id de la compra (UUID).statusescompleteden*.completedyfaileden*.failed.amountCop,feeCopytotalCopson números en pesos. Siempre se cumpletotalCop = amountCop + feeCop.referencees el código de trazabilidad de la compra (texto).ticketes el comprobante del proveedor (objeto) onull. Su forma depende del proveedor.completedAtpuede llegar ennull.
Verificar la firma
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.
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
- Abre API keys en el panel y entra a la llave.
- En la sección Webhook, define la URL y los eventos.
- Usa Probar para enviar un aviso de prueba.
- Consulta o regenera el secreto de la llave.
- 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.
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"] }
urles obligatoria: es el campo de la URL en estePUT. Debe ser https y pública.- El
PUTresponde 200. eventses 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,eventsysecret(whsec_...). El secreto llega solo en la respuesta que lo crea (el primerPUT). UnPUTposterior devuelvesecret: nully conserva el mismo secreto; si lo perdiste, regenéralo en el panel. Valida la firma con esewhsec_. GET /api/v1/collect/webhookdevuelveurlyevents, sin el secreto.POST /api/v1/collect/webhook/testenvía un aviso de prueba firmado (eventotest.ping). Responde 201 conlogId,url,delivered,responseStatus,responseBodyyattempts;delivered: true= tu servidor respondió 2xx. Responde 400 si la llave no tiene URL y 429WEBHOOK_TEST_RATE_LIMITEDcon más de 5 pruebas por minuto por comercio.- El aviso
test.pingllega aunqueeventsde la llave no lo incluya. Se envía una sola vez, sin reintentos, con la misma firma que un aviso real. Sudatatraetest: true,status: "TEST",amount: 0,baseAmount: 0,feeAmount: 0y unareferencecon el prefijoTEST-. 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_DENIEDsin el permiso; 400 si la URL no es https o no es pública; 403FEATURE_DISABLEDsi 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» comoIIONPAY_WEBHOOK_SECRET).
Regenerar el webhook secret
Si sospechas que tu webhook secret ha sido comprometido, puedes regenerarlo desde el dashboard:
- Ve a Integraciones → Webhooks en el panel
- Haz clic en "Regenerar Secret"
- Actualiza tu servidor con el nuevo secret