> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.

# BR Bank Transfer: referência da API de webhooks e correção de assinatura

> A documentação do BR Bank Transfer agora inclui a API de autoatendimento de webhooks e corrige o formato da assinatura e os nomes dos eventos.

5 de junho de 2026Atualização da documentaçãoRevisão recomendada

## 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.

> [!NOTE]
>
> 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 prefixo `v1:`, o timestamp, um ponto como separador e o corpo bruto da requisição.

**Antes**

```
X-Webhook-Signature: sha256=hex(HMAC(secret, timestamp + "." + body))
```

**Depois**

```
X-Webhook-Signature: v1,sha256=hex(HMAC(secret, "v1:" + timestamp + "." + body))
```

Os exemplos de código de validação (JavaScript, Python, Go) foram atualizados de acordo. Os headers entregues são `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 exemplo `transfer.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 se inscreveu em 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

***

**Step 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.

**Step 2**

Verifique se os nomes de eventos em que você se inscreve correspondem ao catálogo de eventos corrigido e substitua os nomes removidos.

**Step 3**

Use o portal de documentação como referência para o registro de webhooks e para a API.

### Prazo

Nenhum.

### Por quê

A API de autoatendimento de webhooks já existia, mas não estava visível no portal, e o formato de assinatura e os nomes de eventos documentados não correspondiam à plataforma. Esta atualização fecha essas lacunas, para que uma integração construída a partir da documentação funcione contra o serviço real.

## Recursos

***

* [Webhooks do BR Bank Transfer](https://docs.lerian.studio/pt/interfaces/ted-jd/ted-webhooks.md)
* [Criar um registro de webhook](https://docs.lerian.studio/pt/reference/interfaces/ted-jd/create-webhook.md)
* [Listar tipos de evento de webhook](https://docs.lerian.studio/pt/reference/interfaces/ted-jd/list-webhook-event-types.md)
* [Lista de erros do Bank Transfer](https://docs.lerian.studio/pt/reference/interfaces/ted-jd/ted-error-list.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.