Eventos

Cuando realizas pagos a través de la API de Pagos a terceros, es importante que tu sistema pueda mantenerse actualizado sobre el estado de cada operación. Para esto, Wompi ofrece un mecanismo de eventos vía webhook, que permite recibir notificaciones automáticas cada vez que ocurre un cambio relevante en el ciclo de vida de un pago.

Estos eventos son enviados a la URL que configures previamente y contienen información detallada sobre la operación, como su estado actual, valores, timestamps y referencias asociadas, entre otros. Esta funcionalidad es clave para mantener la trazabilidad de los pagos y automatizar flujos de negocio basados en su resultado.

tip

Ideal para mantener tu sistema sincronizado con el estado real de las transacciones.

Como configurar la URL de eventos

Puedes registrar una URL para recibir eventos tanto en el ambiente sandbox como en el de producción, desde el dashboard de Wompi.

1. Inicia sesión en tu cuenta principal en nuestro dashboard de comercios.
2. Busca y selecciona la opción Desarrollo en el menú principal.
3. Dentro de Desarrollo, elige la opción Programadores.
4. En la parte superior izquierda, selecciona Pagos a Terceros.
5. Ingresa la URL pública donde recibirás los eventos y guarda los cambios.

Sandbox

Puedes cambiar al modo sandbox y configurar la URL de eventos para este entorno

Generalidades de los eventos

Para que tu endpoint reciba correctamente los eventos, debe cumplir con los siguientes requisitos:

• Método HTTP: Debe aceptar peticiones POST.
• Protocolo: Debe usar HTTPS (no se permiten URLs sin cifrado).
• Accesibilidad: Debe ser públicamente accesible desde internet.
• Códigos de respuesta: Debes responder con un código HTTP 2xx(idealmente 200 OK) para confirmar la recepción del evento.

Importante

Si tu endpoint no responde con un código 2xx, Wompi reintentará el envío del evento hasta 3 veces adicionales.

Tipos de eventos disponibles

Wompi actualmente emite los siguientes eventos relacionados con los pagos:

Cambio de estado de un lote

payout.updated

Ejemplo de evento:

{
  "event": "payout.updated",
  "data": {
    "payout": {
      "id": "04a6e53d-a244-4140-ab9e-48fa541f9fe5",
      "reference": "ref_98765",
      "amountInCents": 7500000,
      "paymentType": "PAYROLL",
      "status": "TOTAL_PAYMENT",
      "totalTransactions": 3,
      "currency": "COP",
      "dispersionDatetime": "2025-05-14T10:30:00.000Z",
      "approvedAt": "2025-05-14T11:00:00.000Z",
      "createdAt": "2025-05-13T09:00:00.000Z"
    }
  },
  "signature": {
    "properties": ["payout.id", "payout.status", "payout.amountInCents"],
    "checksum": "639dc6bd2ac0104f090651c07773b6537f935623cf0ed04894f0687d4c9eebc7"
  },
  "timestamp": 1747673128600,
  "sentAt": "2025-05-15T15:00:00.000Z"
}

Cambio de estado de una transacción

transaction.updated

Ejemplo de evento:

{
  "event": "transaction.updated",
  "data": {
    "transaction": {
      "id": "04a6e53d-a244-4140-ab9e-48fa541f9fe5",
      "payoutId": "payout_12345",
      "amountInCents": 7500000,
      "status": "FAILED",
      "payee": {
        "name": "Juan Pérez",
        "document": "123456789",
        "bank": "BANCOLOMBIA",
        "accountType": "SAVINGS",
        "accountNumber": "1234567890",
        "email": "juan.perez@example.com"
      },
      "failureReason": {
        "code": "C01",
        "message": "La cuenta no existe o está inactiva"
      },
      "currency": "COP",
      "appliedAt": "2025-05-14T13:00:00.000Z",
      "createdAt": "2025-05-13T10:00:00.000Z"
    }
  },
  "signature": {
    "properties": [
      "transaction.id",
      "transaction.status",
      "transaction.amountInCents"
    ],
    "checksum": "82f0e769716170e202edfd348f604bd8461cdeeb416594cde563a890215a5282"
  },
  "timestamp": 1747673128600,
  "sentAt": "2025-05-15T15:00:00.000Z"
}

Seguridad: Validación de integridad

Cada evento enviado por Wompi incluye una firma criptográfica para que puedas validar su autenticidad y asegurarte de que no ha sido modificado en tránsito.

¿Dónde está la firma?: La firma se encuentra en dos lugares del evento:

• En el header HTTP: X-Event-Checksum
• En el body del evento: signature.checksum

La firma se genera a partir de una lista de propiedades (signature.properties) y el uso del secreto de eventos que puedes obtener desde la sección de programadores.

Obtener secreto de eventos

Un Secreto conocido únicamente por el comercio y Wompi, que está disponible en la opción programadores de pagos a terceros, bajo la sección Secretos para integración técnica. Este secreto debe ser custodiado con la máxima seguridad en tus servidores.

Pasos para validar la firma

1. Extrae las propiedades listadas en signature.properties, en el orden en que aparecen.
2. Concatena los valores como una cadena de texto, sin espacios ni separadores.
3. Concatena el campo timestamp.
4. Concatena tu secreto.
5. Genera el hash usando el algoritmo SHA256.
6. Compara el resultado con el valor de X-Event-Checksum o signature.checksum.

Si los valores coinciden, el evento es legítimo. Si no, debes rechazarlo y no procesarlo.

nota

Los properties pueden variar en el tiempo y en cada evento, por eso es muy importante que no los asumas como un arreglo fijo dentro de tu código, sino que siempre los extraigas del evento y utilices apropiadamente en cada validación.

Ejemplo

Validemos la firma del evento visto anteriormente transaction.updated

Paso 1: Concatena los valores de los datos del evento

En el objeto signature del evento debes concatenar el valor de los datos descritos en el campo properties. En este caso tenemos:

• transaction.id: Cuyo valor es 04a6e53d-a244-4140-ab9e-48fa541f9fe5
• transaction.status: Cuyo valor es FAILED
• transaction.amountInCents: Cuyo valor es 7500000

El valor resultante de la concatenación de estos datos, respetando el orden especificados en el arreglo signature.properties es:

04a6e53d-a244-4140-ab9e-48fa541f9fe5FAILED7500000

Paso 2: Concatena el campo timestamp

A la concatenación de las propiedades mostradas en el Paso 1, debes concatenarle también el campo timestamp del evento, que en este caso es 1747673128600. El valor que deberías tener ahora en la cadena en este punto es:

04a6e53d-a244-4140-ab9e-48fa541f9fe5FAILED75000001747673128600

Paso 3: Concatena tu secreto

En este paso debes concatenar tu secreto al string que estás generando hasta este punto. Vamos a asumir, en este ejemplo, que tu secreto es:

prod_events_7b193c8afd7b47949f90d443cb1e1742

Recuerda

El secreto de eventos es distinto a la API Key

El resultado final de la concatenación debería ser:

04a6e53d-a244-4140-ab9e-48fa541f9fe5FAILED75000001747673128600prod_events_7b193c8afd7b47949f90d443cb1e1742

Paso 4: Usa SHA256 para generar el checksum

Con estos datos concatenados apropiadamente, es momento de generar el checksum usando SHA256. Pasando la cadena por este algoritmo se obtiene por ejemplo el siguiente resultado:

82f0e769716170e202edfd348f604bd8461cdeeb416594cde563a890215a5282

La manera en la que usa SHA256 para calcular este valor, varía dependiendo de cada lenguaje de programación. Sin embargo, el resultado debe ser siempre el mismo, dada la naturaleza de este algoritmo seguro de encripción asimétrica.

Paso 5: Compara tu checksum calculado con el proveído en el evento

Al generar tú mismo, el valor del checksum en tu servidor, puedes ahora compararlo con el que llegó en el evento. Si ambos son iguales entonces puedes estar seguro que la información presentada es legítima y enviada por Wompi, y no una suplantación de un tercero. De lo contrario, debes ignorar dicho evento.