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

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 fue liquidado (`settled`) — QR o por llave
`payin.failed`	El cobro fue rechazado por la red (`rejected`) y quedó cerrado
`payin.expired`	El QR o la llave vencieron 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

Los webhooks que te reenviamos van firmados con HMAC-SHA256, usando la Clave que registraste para BREB. Verifica X-Webhook-Signature con tu Clave antes de confiar en el payload. Ver Verificación de firma.