Afeta
Times que integram com webhooks do BR Bank Transfer e qualquer pessoa que usa a referência da API do BR Bank Transfer. Esta atualização se aplica ao portal público de documentação. Não altera o comportamento da API em runtime.
O portal público de documentação é a referência voltada ao cliente. Arquivos de origem do repositório não devem ser tratados como artefatos de integração ou especificações de API baixadas para uso em cliente.
O que mudou
API self-service de webhooks agora documentada
A referência da API agora inclui os endpoints de registro de webhook que estavam faltando no portal: criar, listar, recuperar, atualizar e excluir um registro de webhook, rotacionar seu signing secret e listar os tipos de evento suportados. Os registros têm escopo por tenant, e o signing secret é retornado uma única vez, na criação.Formato de assinatura de webhook corrigido
O esquema de assinatura documentado foi corrigido para corresponder ao que a plataforma envia. A assinatura é um HMAC-SHA256 versionado calculado sobre o prefixov1:, o timestamp, um separador de ponto e o corpo bruto da requisição.
Before
X-Webhook-Event, X-Webhook-Timestamp e X-Webhook-Signature.
Nomes de eventos de webhook corrigidos
O catálogo de eventos agora corresponde aos eventos que a plataforma realmente emite — por exemplotransfer.rejected, os eventos transfer.reconciliation_*, transfer_incoming.completed, transfer_incoming.chargeback e transfer_outgoing.devolution_notified. Nomes que nunca existiram (transfer.failed, transfer.cancelled) foram removidos.
Precisão da referência da API e da configuração
As páginas de referência da API e de configuração do BR Bank Transfer foram alinhadas com a plataforma: o envelope de erro padrão (code, service, category, message, requestId), o código de erro de rate-limit, o intervalo de polling de entrada e as configurações suportadas.
Impacto
Esta é uma atualização de documentação. Ela torna visíveis capacidades de webhook que já existiam e corrige detalhes de referência dos quais uma integração depende. Nenhum comportamento de produto mudou, e nenhuma migração é necessária apenas por esta nota de versão. Se você construiu validação de assinatura de webhook ou se inscreveu em nomes de evento com base na documentação anterior, revise-os — o formato de assinatura anterior e alguns nomes de evento não correspondiam ao que a plataforma envia.
O que você precisa fazer
Se você valida assinaturas de webhook, confirme que seu código usa o formato
v1,sha256= sobre v1: + timestamp + . + o corpo bruto da requisição.Verifique se os nomes de evento aos quais você se inscreve correspondem ao catálogo de eventos corrigido e substitua quaisquer nomes removidos.