Afecta a
Equipos que integran webhooks de BR Bank Transfer y cualquier persona que use la referencia de API de BR Bank Transfer. Esta actualización aplica al portal de documentación pública. No cambia el comportamiento de la API en tiempo de ejecución.
El portal de documentación pública es la referencia de cara al cliente. Los archivos fuente del repositorio no se deberían tratar como artefactos de integración ni como especificaciones de API descargadas para uso del cliente.
Qué cambió
La API de autoservicio de webhooks ahora está documentada
La referencia de API ahora incluye los endpoints de registro de webhooks que faltaban en el portal: crear, listar, recuperar, actualizar y eliminar un registro de webhook, rotar su secreto de firma y listar los tipos de evento admitidos. Los registros tienen alcance por tenant y el secreto de firma se devuelve una vez, en la creación.Formato de firma del webhook corregido
El esquema de firma documentado se corrigió para coincidir con lo que envía la plataforma. La firma es un HMAC-SHA256 versionado calculado sobre el prefijov1:, el timestamp, un separador de punto y el cuerpo sin procesar de la solicitud.
Antes
X-Webhook-Event, X-Webhook-Timestamp y X-Webhook-Signature.
Nombres de evento del webhook corregidos
El catálogo de eventos ahora coincide con los eventos que la plataforma emite realmente — por ejemplotransfer.rejected, los eventos transfer.reconciliation_*, transfer_incoming.completed, transfer_incoming.chargeback y transfer_outgoing.devolution_notified. Se eliminaron los nombres que nunca existieron (transfer.failed, transfer.cancelled).
Precisión de la referencia de API y de la configuración
La referencia de API y las páginas de configuración de BR Bank Transfer se alinearon con la plataforma: el envelope de error estándar (code, service, category, message, requestId), el código de error de rate limit, el intervalo de polling de entrada y los ajustes de configuración admitidos.
Impacto
Esta es una actualización de documentación. Expone capacidades de webhook existentes y corrige detalles de referencia de los que depende una integración. Ningún comportamiento del producto cambió y no se requiere migración solo por esta nota de versión. Si construiste la validación de firma de webhook o te suscribiste a nombres de evento con base en la documentación anterior, revísalos — el formato de firma anterior y algunos nombres de evento no coincidían con lo que envía la plataforma.
Qué debes hacer
1
Si validas firmas de webhook, confirma que tu código use el formato
v1,sha256= sobre v1: + timestamp + . + el cuerpo sin procesar de la solicitud.2
Verifica que los nombres de evento a los que te suscribes coincidan con el catálogo de eventos corregido y reemplaza los nombres eliminados.
3
Usa el portal de documentación como referencia para el registro de webhooks y para la API.