Afeta
Equipes que integram 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. Ela não muda o comportamento da API em runtime.
O portal público de documentação é a referência voltada ao cliente. Recomenda-se que os arquivos-fonte do repositório não sejam tratados como artefatos de integração nem como especificações de API baixadas para uso do cliente.
O que mudou
API de autoatendimento de webhooks agora documentada
A referência da API agora inclui os endpoints de registro de webhook que faltavam no portal: criar, listar, recuperar, atualizar e excluir um registro de webhook, rotacionar o segredo de assinatura dele e listar os tipos de evento aceitos. Os registros têm escopo por tenant, e o segredo de assinatura é retornado uma única vez, na criação.Formato da 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 ponto como separador e o corpo bruto da requisição.
Antes
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 emite de fato — 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
A referência da API e as páginas 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 aceitas.
Impacto
Esta é uma atualização de documentação. Ela torna visíveis recursos de webhook que já existiam e corrige detalhes de referência dos quais uma integração depende. Nenhum comportamento do produto mudou e nenhuma migração é necessária apenas por esta nota de release. Se você construiu a validação de assinatura de webhook ou assinou nomes de eventos com base na documentação anterior, revise esse trabalho — o formato de assinatura anterior e alguns nomes de eventos não correspondiam ao que a plataforma envia.
O que você precisa fazer
1
Se você valida assinaturas de webhook, confirme que o seu código usa o formato
v1,sha256= sobre v1: + timestamp + . + o corpo bruto da requisição.2
Verifique se os nomes de eventos que você assina correspondem ao catálogo de eventos corrigido e substitua os nomes removidos.
3
Use o portal de documentação como referência para o registro de webhooks e para a API.