Webhooks
Descripción
Esta sección centraliza todo lo que necesitas para configurar y probar el flujo completo de webhooks en la plataforma de Pagos-como-Servicio (PaaS) de Passport. Desde la creación de la suscripción hasta la validación end-to-end (E2E) de pagos salientes y entrantes.
Configuración de Webhook en el Tablero de Control
Antes de recibir notificaciones, debes registrar tu Webhook en el Tablero de Control de Passport. A continuación detallo cada campo de la pantalla de “Crear Webhook”:
El administrador de la Fintech debe:
Ingresar al Tablero de Control de Passport.
Acceder a Plataforma > Webhooks
Seleccionar Crear Webhook +
Configurar el Webhook
Hacer click en Guardar


Caso esté configurado en el modo de reintentos, cuando ocurra un error en la URL de callback, el reintento se enviará con todos los eventos dentro de un array.
Configuración de Múltiples Webhooks
La plataforma admite varias configuraciones de webhooks, lo que le permite configurar uno o varios webhooks para recibir distintos eventos en endpoints diferentes. Esta flexibilidad le permite adaptar el manejo de eventos según sus necesidades específicas.
Tenga en cuenta que no se permite suscribirse al mismo evento en múltiples extremos.
Si tiene un webhook configurado, simplemente seleccione Nuevo Webhook + y continúe configurando su nueva URL de callback junto con la información requerida presentada en la sección: Configuración de Webhook en el Panel de Control anterior.
Detalles de los Parámetros de Configuración
Campos | Descripción |
|---|---|
URL Callback | Dirección HTTPS a la que Passport enviará las notificaciones. Debe ser accesible públicamente. |
Token de Segredo | Clave que usarás para calcular/verificar la firma HMAC-SHA256. ¡Guárdala en secreto! |
Modo de Entrega | Mecanismo de retry que quieras usar (“Una Vez" o “Reintentar”). |
Webhook Activado | Selector SI/NO para habilitar o deshabilitar las notificaciones. |
Eventos | Tipo de Eventos, basado en los tipos para Pagos y Gestión de Llaves Bre-B |
Firma de Webhook V2
Passport proporciona el encabezado X-Passport-Signature-V2 para verificar la autenticidad de los webhooks e implementar protección contra ataques de repetición (replay attacks).
A diferencia de una firma calculada directamente a partir de los bytes originales transmitidos, V2 firma una representación canónica del mismo payload JSON. El cuerpo canónico utiliza las claves ordenadas y elimina los espacios innecesarios, de manera equivalente a:
Passport incluye la marca de tiempo (timestamp) en el mensaje firmado y también la envía por separado en el encabezado X-Passport-Timestamp.
El mensaje utilizado para calcular el HMAC debe construirse de la siguiente manera:
Verifique la firma HMAC-SHA256 utilizando el Secret Token de su webhook y utilice el timestamp firmado para rechazar solicitudes repetidas y prevenir ataques de repetición.
Importante: La versión V2 no incluye un nonce.
Las timestamps (marcas de tiempo) es en el formato de tiempo epoch en segundos.
Comportamiento de 'Reintento' en los Webhooks
Cuando el Modo de Entrega está configurado como 'Reintentar' tras un fallo del webhook, la plataforma intentará reenviarlos hasta 12 veces. El primer intento se realiza 1 segundo después del evento de fallo, es decir:
1_2*_0 = 1s para el primer reintento.
1_2*_1 = 2s para el segundo.
1_2*_2 = 4s para el tercero.
1_2*_3 = 8s para el cuarto.
Selección de Eventos
Bajo el título Eventos elige la categoría Pagos y marca uno o varios (el nombre del evento en la notificación está en paréntesis):
Inbound (Pago Entrante) (
payment.inbound.received)El pago fue enviado exitosamente hacia ti dentro de la red Bre-B. Es decir, estás recibiendo un pago (tú o el cliente que administras).
Confirmed (Pago Confirmado) (
payment.inbound.confirmedopayment.outbound.confirmed)El pago entrante o saliente fue confirmado por el banco originador o receptor.
Settled (Pago Liquidado) (
payment.inbound.settledopayment.outbound.settled)El pago fue completado en el banco originador o receptor.
Rejected (
payment.inbound.rejectedopayment.outbound.rejected)El pago fue rechazado. Revisa el cuerpo de la respuesta para más detalles.
Flujo de Eventos (Inbound - Entrante)
Para transacciones entrantes (hacia tu cuenta o las de tus clientes), el flujo simple es:
payment.inbound.received → payment.inbound.confirmed → payment.inbound.settled
Flujo de Eventos (Outbound - Saliente)
Para transacciones salientes (desde tu cuenta o las de tus clientes), los eventos principales son:
payment.outbound.confirmed → payment.outbound.settled
Rechazo de Pagos
Si las validaciones en el MOL resultan en que un pago se clasifique como Rejected, esto puede ocurrir en cualquier etapa del proceso. El webhook entregará el código de estado y una descripción detallada del error detectado.
payment.inbound.rejectedpayment.outbound.rejected
Ejemplos de Eventos
Pago Entrante (Received)
El evento payment.inbound.received ocurre cuando una transacción se envía exitosamente hacia tu cuenta o en la cuenta de tu cliente. Puede originarse por una transacción a una llave o al código QR. Análogamente, payment.outbound.settled indica que tu transacción se liquidó en el banco receptor.
No es el estado final del pago; se recomienda esperar el evento de liquidación: SETTLED o REJECTED.
Pago Confirmado (Confirmed)
El evento payment.inbound.confirmed señala la confirmación emitida por el Participante (banco receptor) sobre la transacción. Esta confirmación sucede si se cumplen condiciones como la validez de la llave y su asociación a una cuenta existente en el banco receptor (entre otras). Tras el evento inbound inicial, payment.inbound.confirmed indica un curso exitoso. Si surge algún problema a nivel de Nodo, MOL o Banco, el siguiente evento será payment.inbound.rejected. Si la dirección es saliente, verás payment.outbound.confirmed o payment.outbound.rejected en caso de inconsistencia.
Pago Liquidado (Settled)
Uno de los eventos más relevantes: payment.inbound.settled o payment.outbound.settled marca la transferencia exitosa de fondoshacia/desde la cuenta del cliente. En otras palabras, el cliente completó el pago por el producto o servicio y los fondos ya están disponibles en la cuenta. Para outbound, se refiere al movimiento de fondos desde una cuenta hacia la cuenta de destino.
Pago Rechazado (Rejected)
En caso de que cualquier actor en el flujo de pago encuentre algún problema, se devolverá un estado de rechazo. Esto indica que el movimiento de fondos no se llevará a cabo dentro de la red ni entre cuentas. Tenga en cuenta que este estado es definitivo. En consecuencia, el pago debe revisarse minuciosamente para identificar cualquier código de estado de error. Los webhooks correspondientes mostrarán el error específico en el campo apropiado:
La dirección del pago aparecerá reflejada en los eventos:
payment.inbound.rejectedpara pagos entrantes rechazados.payment.outbound.rejectedpara pagos salientes rechazados.
Eventos de Gestión de Llaves
Suscríbase a los eventos de gestión de llaves que necesite para recibir notificaciones cuando una operación sobre una llave sea confirmada o rechazada.
Evento | Cuándo se envía |
|---|---|
| Se confirmó la creación de la llave. Su estado es |
| Se rechazó la creación de la llave. Su estado es |
| Se confirmó la eliminación de la llave. |
| Se confirmó la suspensión de la llave. |
| Se confirmó la activación de la llave. |
Llaves: Ejemplos de Eventos
Llave Creada (key.created)
Llave Eliminada (key.deleted)
Llave Suspendida (key.suspended)
Llave Activada (key.activated)
Nota: Los nombres de los eventos, campos y valores de estado se mantienen en inglés, tal como se utilizan en la API de Passport, para garantizar la compatibilidad con las integraciones.