> ## 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 atualização da documentação de assinatura

> A documentação do BR Bank Transfer agora inclui a API self-service de webhooks e corrige o formato de assinatura de webhook e os nomes de eventos.

<Badge stroke icon="calendar-days" iconType="regular">5 de junho de 2026</Badge> <Badge stroke icon="file-code" iconType="regular">Atualização de documentação</Badge> <Badge color="purple" size="lg" stroke icon="eye" iconType="regular">Revisão recomendada</Badge>

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

<Note>
  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.
</Note>

## 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 prefixo `v1:`, o timestamp, um separador de ponto e o corpo bruto da requisição.

**Before**

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

**After**

```
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 realmente emite — 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

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

***

<Steps>
  <Step>
    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.
  </Step>

  <Step>
    Verifique se os nomes de evento aos quais você se inscreve correspondem ao catálogo de eventos corrigido e substitua quaisquer nomes removidos.
  </Step>

  <Step>
    Use o portal de documentação como referência para o registro de webhook e para a API.
  </Step>
</Steps>

### Prazo

Nenhum.

### Por quê

A API self-service de webhooks existia, mas não estava visível no portal, e o formato de assinatura e os nomes de evento 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

***

* [BR Bank Transfer webhooks](/pt/midaz/plugins/ted/ted-webhooks)
* [Create a webhook registration](/pt/reference/midaz/plugins/ted/create-webhook)
* [List webhook event types](/pt/reference/midaz/plugins/ted/list-webhook-event-types)
* [Bank Transfer error list](/pt/reference/midaz/plugins/ted/ted-error-list)