> ## 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: webhook API reference and signature update

> The BR Bank Transfer documentation now includes the webhook self-service API and corrects the webhook signature format and event names.

<Badge stroke icon="calendar-days" iconType="regular">June 5, 2026</Badge> <Badge stroke icon="file-code" iconType="regular">Documentation update</Badge> <Badge color="purple" size="lg" stroke icon="eye" iconType="regular">Review recommended</Badge>

## Affects

***

Teams integrating BR Bank Transfer webhooks, and anyone using the BR Bank Transfer API reference.

This update applies to the public documentation portal. It does not change the runtime API behavior.

<Note>
  The public documentation portal is the customer-facing reference. Repository source files should not be treated as integration artifacts or downloaded API specifications for client use.
</Note>

## What changed

***

### Webhook self-service API now documented

The API reference now includes the webhook registration endpoints that were missing from the portal: create, list, retrieve, update, and delete a webhook registration, rotate its signing secret, and list the supported event types. Registrations are scoped per tenant, and the signing secret is returned once, at creation.

### Webhook signature format corrected

The documented signature scheme was corrected to match what the platform sends. The signature is a versioned HMAC-SHA256 computed over the prefix `v1:`, the timestamp, a dot separator, and the raw request body.

**Before**

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

**After**

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

The validation code samples (JavaScript, Python, Go) were updated accordingly. The delivered headers are `X-Webhook-Event`, `X-Webhook-Timestamp`, and `X-Webhook-Signature`.

### Webhook event names corrected

The event catalog now matches the events the platform actually emits — for example `transfer.rejected`, the `transfer.reconciliation_*` events, `transfer_incoming.completed`, `transfer_incoming.chargeback`, and `transfer_outgoing.devolution_notified`. Names that never existed (`transfer.failed`, `transfer.cancelled`) were removed.

### API reference and configuration accuracy

The BR Bank Transfer API reference and configuration pages were aligned with the platform: the standard error envelope (`code`, `service`, `category`, `message`, `requestId`), the rate-limit error code, the inbound polling interval, and the supported configuration settings.

## Impact

***

This is a documentation update. It surfaces existing webhook capabilities and corrects reference details that an integration relies on. No product behavior changed, and no migration is required from this release note alone.

If you built webhook signature validation or subscribed to event names based on the previous documentation, review them — the previous signature format and some event names did not match what the platform sends.

## What you need to do

***

<Steps>
  <Step>
    If you validate webhook signatures, confirm your code uses the `v1,sha256=` format over `v1:` + timestamp + `.` + the raw request body.
  </Step>

  <Step>
    Check that the event names you subscribe to match the corrected event catalog, and replace any removed names.
  </Step>

  <Step>
    Use the documentation portal as the reference for webhook registration and the API.
  </Step>
</Steps>

### Deadline

None.

### Why

The webhook self-service API existed but was not visible in the portal, and the documented signature format and event names did not match the platform. This update closes those gaps so an integration built from the documentation works against the real service.

## Resources

***

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