Webhooks (Bre-B)

Bre-B notifica los cambios de estado a nuestro gateway. Verificamos la firma, actualizamos la transacción y el balance, y enviamos el evento a tu webhookUrl configurada, con reintentos. Puedes configurar una URL específica para BREB o una única URL para toda la región CO.

Secuencia de eventos de Bre-B

Flujo	Secuencia
Entrante (pay-in)	`received` → `confirmed` → `settled`
Saliente (pay-out)	`confirmed` → `settled`
Cualquiera	`rejected` termina el flujo

Mapeo a estado interno:

Evento Bre-B	Estado interno
`*.settled`	`COMPLETED` (terminal, mueve el balance)
`*.rejected`	`FAILED` (terminal)
`.received` / `.confirmed`	`PROCESSING` (informativo, no se reenvía)

Eventos enviados a tu webhook

El nombre del evento llega en el header X-Webhook-Event (no dentro del body).

Evento	Cuándo
`payin.completed`	El cobro QR fue liquidado (`settled`)
`payin.failed`	El cobro fue rechazado
`payin.expired`	El QR venció sin pago (estado final `EXPIRED`)
`payout.completed`	La dispersión se liquidó
`payout.failed`	La dispersión fue rechazada

Payload de payin.completed / payin.failed / payout.completed / payout.failed:

{
  "txId": "a1b2c3d4e5f64a7b8c9d0e1f2a3b4c5d",
  "type": "PAYIN",
  "status": "COMPLETED",
  "amount": 50000,
  "currency": "COP",
  "feeCharged": 1500,
  "netAmount": 48500,
  "e2eId": "E2E-20260601-0001",
  "updatedAt": "2026-06-01T10:05:00.000Z"
}

Campo	Descripción
`txId`	ID de la transacción (coincide con el de la creación)
`type`	`PAYIN` o `PAYOUT`
`status`	`COMPLETED` o `FAILED`
`feeCharged`	Fee cobrado en pesos COP (`0` si falló)
`netAmount`	Monto neto acreditado — solo en `payin.completed`
`e2eId`	Identificador end-to-end de la red Bre-B

Payload de payin.expired:

{
  "txId": "a1b2c3d4e5f64a7b8c9d0e1f2a3b4c5d",
  "type": "PAYIN",
  "status": "EXPIRED",
  "amount": 50000,
  "currency": "COP",
  "failureReason": "Transaction expired without provider confirmation",
  "expiredAt": "2026-06-01T10:15:00.000Z"
}

Verificación de firma (entrada al gateway)

A diferencia de Nequi, los webhooks que Bre-B nos envía llegan firmados con HMAC-SHA256. Nuestro gateway verifica la firma del header contra el secret compartido con comparación de tiempo constante antes de procesar. Esto es interno — no cambia el formato del webhook que tú recibes.

Sandbox

En modo sandbox el desenlace se simula automáticamente al crear la transacción: recibes el webhook de inmediato con el campo extra "sandbox": true.