Ejemplos de webhooks - OnePay Documentación

Esta página contiene ejemplos de todos los eventos de webhook disponibles en OnePay, organizados por categoría.

Todos los webhooks incluyen un objeto event con la siguiente estructura:

type: Tipo de evento (ej. payment.approved)
timestamp: Marca de tiempo Unix del evento
environment: Entorno donde ocurrió el evento (live o test)

Pagos (Cobros)

Eventos disponibles

payment.created - Cobro creado
payment.deleted - Cobro eliminado
payment.rejected - Cobro rechazado
payment.approved - Cobro aprobado
payment.expired - Cobro expirado

Estados posibles

pending - Pendiente
cancelled - Cancelado
approved - Aprobado
declined - Rechazado
in_progress - En progreso
refunded - Reembolsado
expired - Expirado

Ejemplo

{
  "payment": {
    "id": "99a337b3-3a7d-4e0b-b5ea-7098b562d4dd",
    "status": "pending",
    "currency": "COP",
    "amount": "180000",
    "external_id": "814",
    "phone": "+573155555555",
    "title": "Renta PAZCNTPDG0 mes mayo Rondoo",
    "description": "PAZCNTPDG0",
    "document_link": "https://s3.us-east-2.amazonaws.com/rondoo.co/invoices/8b4995be-1c01-47f6-8ee2-d0d60022f746",
    "allow_credit": true,
    "allow_debit": true,
    "created_at": "2023-07-13T15:42:12.000000Z",
    "paid_at": null,
    "deletable": false,
    "amount_label": "$180.000",
    "payment_link": "https://wa.me/+573126761889?text=Pagar ref: 99a337b3-3a7d-4e0b-b5ea-7098b562d4dd",
    "message_status": "delivered",
    "customer": {
      "first_name": "Daniela",
      "last_name": "Lozano",
      "email": "danielaloza@gmail.com",
      "phone": "+573155555555"
    }
  },
  "event": {
    "type": "payment.created",
    "timestamp": 1689262934,
    "environment": "live"
  }
}

Cargos (Débitos)

Eventos disponibles

charge.created - Cargo creado
charge.processing - Cargo en procesamiento
charge.paid - Cargo pagado
charge.failed - Cargo fallido
charge.refunded - Cargo reembolsado
charge.disputed - Cargo en disputa

Estados posibles

created - Creado
processing - Procesando
paid - Pagado
failed - Fallido
refunded - Reembolsado
disputed - En disputa

Ejemplo

{
  "charge": {
    "id": "9bf2bc44-28d4-4693-9896-7fc1fe1f5b65",
    "description": "Pago factura 001-2024",
    "amount": 63040,
    "amount_label": "$63.040",
    "currency": "COP",
    "status": "paid",
    "payment_method_type": "CreditCard",
    "payment_method_id": "3f8b7a21-1d4a-4d2e-8f1a-17e2f1e6b9ab",
    "source": {
      "type": "Payment",
      "id": "12e34567-89ab-4cde-f012-3456789abcde"
    },
    "created_at": "2024-10-20T12:00:00.000000Z",
    "paid_at": "2024-10-20T12:10:10.000000Z",
    "remarks": null,
    "is_test": true,
    "network_id": "prov-123",
    "external_id": "EXT-12345",
    "method": {
      "id": "3f8b7a21-1d4a-4d2e-8f1a-17e2f1e6b9ab",
      "brand": "visa",
      "label": "Personal",
      "last_four": "4242",
      "expiration_date": "12/2028",
      "customer_id": "1c2d3e4f-5678-90ab-cdef-111213141516",
      "created_at": "2024-09-15T10:20:30.000000Z",
      "country": "CO"
    },
    "customer": {
      "id": "4e5f6a7b-8c9d-0e1f-2345-6789abcdef01",
      "first_name": "Juan",
      "last_name": "Pérez",
      "email": "juan.perez@example.com",
      "phone": "+573001112233",
      "document_type": "CC",
      "document_number": "1234567890",
      "created_at": "2024-09-10T09:00:00.000000Z",
      "is_test": true
    }
  },
  "event": {
    "type": "charge.paid",
    "timestamp": 1689262934,
    "environment": "live"
  }
}

Dispersiones

Eventos disponibles

cashout.created - Dispersión creada
cashout.completed - Dispersión completada
cashout.processing - Dispersión en procesamiento
cashout.cancelled - Dispersión cancelada
cashout.rejected - Dispersión rechazada
cashout.require_approval - Dispersión requiere aprobación

Estados posibles

scheduled - Programada
to_process - Por procesar
processing - Procesando
processed - Procesada
failed - Fallida
cancelled - Cancelada
turbo_onboarding - En onboarding turbo

Ejemplo

{
  "cashout": {
    "id": "99a337b3-3a7d-4e0b-b5ea-7098b562d4dd",
    "customer_id": "4bbd4a30-a29a-4fec-be47-ec2dcf49ebe8",
    "account_id": "e5b15794-5b36-4c41-9c8f-d7cd4c8602cc",
    "is_test": true,
    "amount": 180000,
    "status": "to_process",
    "scheduled_at": "2024-08-17T15:42:12.000000Z",
    "created_at": "2024-08-15T12:12:32.000000Z",
    "external_id": "814"
  },
  "event": {
    "type": "cashout.created",
    "timestamp": 1689262934,
    "environment": "live"
  }
}

Suscripciones

Eventos disponibles

subscription.created - Suscripción creada
subscription.canceled - Suscripción cancelada
subscription.active - Suscripción activa
subscription.frozen - Suscripción congelada
subscription.deleted - Suscripción eliminada

Estados posibles

created - Creada
canceled - Cancelada
active - Activa
frozen - Congelada
deleted - Eliminada

Ejemplo

{
  "subscription": {
    "id": "9c799dbc-c453-4798-8a1f-0ec386dba964",
    "name": "Test subs",
    "status": "created",
    "description": "Test subs",
    "reference_price_in_cents": "200000",
    "currency": "COP",
    "amount_in_cents": 100000,
    "cicle_frequency": "daily",
    "cicles": 1000,
    "current_cicle": 0,
    "allows": {
      "credit_card": true,
      "debit_card": true,
      "account": true
    },
    "start_date": "2024-07-05T00:00:00.000000Z",
    "trial": {
      "enabled": false,
      "days": 0
    },
    "customer": {
      "id": "9c799dbc-c453-4798-8a1f-0ec386dba964",
      "first_name": "Juan",
      "last_name": "Pérez",
      "email": "juan@example.com",
      "phone": "+573001112233"
    },
    "plan": null
  },
  "event": {
    "type": "subscription.created",
    "timestamp": 1689262938,
    "environment": "live"
  }
}

Cuentas bancarias

Eventos disponibles

account.pending - Cuenta pendiente
account.connected - Cuenta conectada
account.disconnected - Cuenta desconectada
account.validated - Cuenta validada
account.uncompleted - Cuenta incompleta

Estados posibles

PENDING - Pendiente
CONNECTED - Conectada
DISCONNECTED - Desconectada
VALIDATED - Validada
UNCOMPLETED - Incompleta

Ejemplo

{
  "account": {
    "bank_id": "9b90ba74-4a99-4beb-827d-2df3236c2549",
    "subtype": "SAVINGS",
    "authorization": false,
    "id": "9b90ba74-5743-4eb3-a6a8-a1503919c98f",
    "status": "PENDING",
    "title": "Swift Group **** 7890",
    "created_at": "2024-03-14T23:30:57.000000Z",
    "method_type": "account",
    "bank": {
      "id": "9b90ba74-4a99-4beb-827d-2df3236c2549",
      "name": "Swift Group",
      "code": "1234",
      "logo": "https://example.com/logo.png"
    }
  },
  "event": {
    "type": "account.pending",
    "timestamp": 1689262934,
    "environment": "live"
  }
}

Links de captura

Eventos disponibles

connect_link.completed - Link de captura completado

Ejemplo

{
  "customer_id": "9957858a-c2f1-4f18-a5c2-216b4127e278",
  "payment_method_type": "card",
  "payment_method_id": "4bbd4a30-a29a-4fec-be47-ec2dcf49ebe8",
  "connect_link": {
    "id": "0195f36f-7cde-7113-a335-b94ce34a2755",
    "customer_id": "9957858a-c2f1-4f18-a5c2-216b4127e278",
    "single_use": false,
    "visits": 0,
    "completed": 0,
    "external_id": "31231231231",
    "allows": {
      "credit_card": true,
      "debit_card": true,
      "account": true
    },
    "created_at": "2025-04-01T22:18:44.000000Z",
    "url": "https://pagos.onepay.test/connect-link/0195f36f-7cde-7113-a335-b94ce34a2755"
  },
  "event": {
    "type": "connect_link.completed",
    "timestamp": 1689262934,
    "environment": "live"
  }
}

Facturas

Eventos disponibles

invoice.created - Factura creada
invoice.paid - Factura pagada
invoice.cancelled - Factura cancelada

Ejemplo

{
  "invoice": {
    "reference": "1024567",
    "id": "invoice_id",
    "name": "invoice_name",
    "provider_id": "provider_id",
    "provider": "provider",
    "status": "paid",
    "remarks": "remarks",
    "amount": 10000,
    "phone": "+5712345678",
    "email": "email@example.com",
    "document_url": "",
    "payment_id": "",
    "metadata": {
      "custom_field": "custom_value"
    },
    "created_at": "2025-04-01T22:18:44.000000Z"
  },
  "event": {
    "type": "invoice.paid",
    "timestamp": 1689262934,
    "environment": "live"
  }
}

Servicios públicos

Eventos disponibles

utility.paid - Servicio pagado
utility.rejected - Servicio rechazado

Estados posibles

created - Creado
paid - Pagado
rejected - Rechazado

Ejemplo

{
  "utility": {
    "id": "9d1cd37a-a6bc-472d-b4e6-c913769d005a",
    "group_id": "Kirlin Group, 2381762387",
    "provider_id": "9d1cd37a-94e5-4cf1-aa7c-daac8ebf4ed9",
    "provider_name": "Kirlin Group",
    "amount": 250000,
    "reference": "2381762387",
    "status": "rejected",
    "remarks": "La deuda actual es diferente."
  },
  "event": {
    "type": "utility.rejected",
    "timestamp": 1689262934,
    "environment": "live"
  }
}

Saldo

Eventos disponibles

balance.updated - Saldo actualizado

Ejemplo

{
  "balance": {
    "amount": 32489143.91,
    "amount_in_cents": 3248914391,
    "currency": "COP"
  },
  "event": {
    "type": "balance.updated",
    "timestamp": 1689262934,
    "environment": "live"
  }
}

Transacciones

Eventos disponibles

wallet.transaction.created - Transacción creada

Ejemplo

{
  "transaction": {
    "id": "0194b42f-5515-7245-b9f4-193c92f37b8c",
    "type": "deposit",
    "amount": 1000,
    "label": "$1.000",
    "concept": "Transferencia de fondos",
    "subtype": "PAYOUT",
    "confirmed": true,
    "node_type": "CashoutLine",
    "created_at": "2025-01-29T22:29:48.000000Z",
    "node": {
      "id": "9e16627d-1eb9-46c4-ba19-b229ea77d68e",
      "customer_id": "9957858a-c2f1-4f18-a5c2-216b4127e278",
      "account_id": "9d005522-fad4-44c2-9012-1dbb871322b5",
      "is_test": false,
      "amount": 1000,
      "status": "processed",
      "scheduled_at": null,
      "created_at": "2025-01-29T22:29:48.000000Z",
      "external_id": null,
      "method": "TURBO",
      "discount_to_destination": false
    }
  },
  "balance": {
    "id": "268efd35-772c-41ef-bcf5-0028d9db7092",
    "balance": 100000,
    "label": "$100.000"
  },
  "event": {
    "type": "wallet.transaction.created",
    "timestamp": 1689262934,
    "environment": "live"
  }
}

Seguridad de webhooks

Importante: Siempre debes verificar la firma HMAC-SHA256 de los webhooks para asegurar que provienen de OnePay.

Cada webhook incluye los siguientes headers de seguridad:

x-onepay-signature: Firma HMAC-SHA256 del payload
x-onepay-timestamp: Timestamp Unix de cuando se envió el webhook

Validación de firma

JavaScript (Node.js)
Python
PHP

const crypto = require('crypto');

function verifyWebhookSignature(req) {
  const signature = req.headers['x-signature'];
  const secret = process.env.ONEPAY_WEBHOOK_SECRET; // wh_tok_...

  // El body debe ser el raw string, NO el objeto parseado
  const rawBody = JSON.stringify(req.body);

  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(rawBody)
    .digest('hex');

  return signature === expectedSignature;
}

import hmac
import hashlib

def verify_webhook_signature(signature, payload, secret):
    expected_signature = hmac.new(
        secret.encode('utf-8'),
        payload.encode('utf-8'),
        hashlib.sha256
    ).hexdigest()

    return hmac.compare_digest(signature, expected_signature)

function verifyWebhookSignature($signature, $payload, $secret) {
    $expectedSignature = hash_hmac('sha256', $payload, $secret);

    return hash_equals($expectedSignature, $signature);
}

Reintentos

OnePay reintenta el envío de webhooks hasta 6 veces con backoff exponencial si tu servidor no responde o devuelve un error:

Intento inmediato
5 minutos después
15 minutos después
1 hora después
4 horas después
12 horas después

Asegúrate de que tu endpoint responda con un código 2xx (preferiblemente 200) dentro de 5 segundos para confirmar la recepción del webhook.

Idempotencia

Usa el campo event.id para implementar idempotencia y evitar procesar el mismo evento múltiples veces:

// Ejemplo de manejo idempotente
const processedEvents = new Set();

function handleWebhook(webhook) {
  const eventId = webhook.event.id;

  if (processedEvents.has(eventId)) {
    console.log('Event already processed, skipping');
    return;
  }

  // Procesar el evento...
  processedEvents.add(eventId);
}

API

Métodos de pago

Recaudo

Dispersiones

Webhooks

Fintech as a service

​Pagos (Cobros)

​Eventos disponibles

​Estados posibles

​Ejemplo

​Cargos (Débitos)

​Eventos disponibles

​Estados posibles

​Ejemplo

​Dispersiones

​Eventos disponibles

​Estados posibles

​Ejemplo

​Suscripciones

​Eventos disponibles

​Estados posibles

​Ejemplo

​Cuentas bancarias

​Eventos disponibles

​Estados posibles

​Ejemplo

​Links de captura

​Eventos disponibles

​Ejemplo

​Facturas

​Eventos disponibles

​Ejemplo

​Servicios públicos

​Eventos disponibles

​Estados posibles

​Ejemplo

​Saldo

​Eventos disponibles

​Ejemplo

​Transacciones

​Eventos disponibles

​Ejemplo

​Seguridad de webhooks

​Validación de firma

​Reintentos

​Idempotencia

Pagos (Cobros)

Eventos disponibles

Estados posibles

Ejemplo

Cargos (Débitos)

Eventos disponibles

Estados posibles

Ejemplo

Dispersiones

Eventos disponibles

Estados posibles

Ejemplo

Suscripciones

Eventos disponibles

Estados posibles

Ejemplo

Cuentas bancarias

Eventos disponibles

Estados posibles

Ejemplo

Links de captura

Eventos disponibles

Ejemplo

Facturas

Eventos disponibles

Ejemplo

Servicios públicos

Eventos disponibles

Estados posibles

Ejemplo

Saldo

Eventos disponibles

Ejemplo

Transacciones

Eventos disponibles

Ejemplo

Seguridad de webhooks

Validación de firma

Reintentos

Idempotencia