> For the complete documentation index, see [llms.txt](https://docs.barte.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.barte.com/banking/api/webhooks/webhooks.md).

# Configuração e Gerenciamento

A Barte envia notificações via webhook quando há mudanças no status das contas e atualizações sobre pagamentos, saques e depósitos.

## Configuração

A URL de callback é configurada durante o onboarding ou via API (veja [Gerenciamento de Webhooks](#gerenciamento-de-webhooks)). Requisitos:

* HTTPS obrigatório
* Responder com status `2xx` em até 30 segundos
* Suportar retentativas (até 5 tentativas com backoff exponencial)

### Headers

| Header         | Descrição          |
| -------------- | ------------------ |
| `Content-Type` | `application/json` |

## Gerenciamento de Webhooks

### Ciclo de Vida

#### Fluxo de Cadastro

```mermaid
sequenceDiagram
    participant P as Parceiro
    participant B as Banking API

    P->>B: POST /v1/webhooks
    B-->>P: 201 Created (webhook cadastrado)
    P->>B: GET /v1/webhooks
    B-->>P: 200 OK (lista de webhooks)
    P->>B: PUT /v1/webhooks/{id}
    B-->>P: 202 Accepted (webhook atualizado)
```

#### Fluxo de Ativação e Inativação

```mermaid
sequenceDiagram
    participant P as Parceiro
    participant B as Banking API

    P->>B: PATCH /v1/webhooks/{id}/active (isActive: false)
    B-->>P: 200 OK (webhook inativado)
    P->>B: PATCH /v1/webhooks/{id}/active (isActive: true)
    B-->>P: 200 OK (webhook reativado)
    Note over B: Somente webhooks ativos recebem notificações
```

#### Fluxo de Notificação

```mermaid
sequenceDiagram
    participant P as Parceiro
    participant B as Banking API

    P->>B: POST /v1/webhooks (eventType: cash_in.update)
    B-->>P: 201 Created
    Note over B: PIX recebido na conta
    B-->>P: Notificação cash_in.update (SUCCESS)
```

### POST /v1/webhooks

Cadastra um ou mais webhooks para receber notificações de eventos da instituição financeira autenticada.

**Request:**

```bash
curl --request POST \
  --url 'https://api-banking.barte.com/v1/webhooks' \
  --cert client.pem \
  --key client-key.pem \
  --header 'Authorization: Bearer {token}' \
  --header 'Content-Type: application/json' \
  --data '[
    {
      "url": "https://meu-sistema.com.br/webhooks/pix",
      "eventType": "cash_in.update",
      "description": "Notificações de PIX recebido"
    },
    {
      "url": "https://meu-sistema.com.br/webhooks/kyc",
      "eventType": "account_holder_status.update",
      "description": "Notificações de status de conta (v2)"
    }
  ]'
```

#### Campos — Request

| Campo         | Tipo   | Obrigatório | Validação                                                                                                             |
| ------------- | ------ | ----------- | --------------------------------------------------------------------------------------------------------------------- |
| `url`         | String | Sim         | Deve usar HTTPS. Ex: `https://meu-sistema.com.br/webhook`                                                             |
| `eventType`   | String | Sim         | Enum: `cash_in.update`, `cash_out.update`, `cash_out.refund`, `account_status.update`, `account_holder_status.update` |
| `description` | String | Não         | Descrição do webhook                                                                                                  |

> O corpo da requisição é uma **lista** de webhooks. É possível cadastrar múltiplos webhooks em uma única chamada.

**Response — 201 Created:**

```json
[
  {
    "id": 1,
    "url": "https://meu-sistema.com.br/webhooks/pix",
    "eventType": "cash_in.update",
    "description": "Notificações de PIX recebido",
    "isActive": true
  },
  {
    "id": 2,
    "url": "https://meu-sistema.com.br/webhooks/kyc",
    "eventType": "account_holder_status.update",
    "description": "Notificações de status de conta (v2)",
    "isActive": true
  }
]
```

#### Campos — Response

| Campo         | Tipo    | Descrição                              |
| ------------- | ------- | -------------------------------------- |
| `id`          | Int     | Identificador único do webhook         |
| `url`         | String  | URL de destino das notificações        |
| `eventType`   | String  | Tipo de evento cadastrado              |
| `description` | String  | Descrição do webhook (pode ser `null`) |
| `isActive`    | Boolean | Indica se o webhook está ativo         |

**Response — 400 Bad Request (URL sem HTTPS):**

```json
{
  "errors": [
    {
      "code": "BNK-0501",
      "title": "Invalid request params",
      "description": "Error in request url - Webhook URL must use HTTPS"
    }
  ],
  "metadata": {
    "totalRecords": 1,
    "totalPages": 1,
    "requestDatetime": "2026-01-30T15:30:00Z"
  }
}
```

**Response — 404 Not Found (instituição financeira não encontrada):**

```json
{
  "errors": [
    {
      "code": "BNK-0402",
      "title": "Webhook flow error",
      "description": "Financial institution for webhook not found"
    }
  ],
  "metadata": {
    "totalRecords": 1,
    "totalPages": 1,
    "requestDatetime": "2026-01-30T15:30:00Z"
  }
}
```

**Status Codes:**

| Status             | Descrição                             |
| ------------------ | ------------------------------------- |
| `201 Created`      | Webhook(s) cadastrado(s) com sucesso  |
| `400 Bad Request`  | Dados inválidos ou URL sem HTTPS      |
| `401 Unauthorized` | Token inválido ou expirado            |
| `403 Forbidden`    | Autoridade `PAYFAC` necessária        |
| `404 Not Found`    | Instituição financeira não encontrada |

***

### GET /v1/webhooks

Lista todos os webhooks cadastrados para a instituição financeira autenticada.

**Request:**

```bash
curl --request GET \
  --url 'https://api-banking.barte.com/v1/webhooks' \
  --cert client.pem \
  --key client-key.pem \
  --header 'Authorization: Bearer {token}'
```

**Response — 200 OK:**

```json
[
  {
    "id": 1,
    "url": "https://meu-sistema.com.br/webhooks/pix",
    "eventType": "cash_in.update",
    "description": "Notificações de PIX recebido",
    "isActive": true
  },
  {
    "id": 2,
    "url": "https://meu-sistema.com.br/webhooks/kyc",
    "eventType": "account_holder_status.update",
    "description": "Notificações de status de conta (v2)",
    "isActive": false
  }
]
```

**Status Codes:**

| Status             | Descrição                             |
| ------------------ | ------------------------------------- |
| `200 OK`           | Lista de webhooks retornada           |
| `401 Unauthorized` | Token inválido ou expirado            |
| `403 Forbidden`    | Autoridade `PAYFAC` necessária        |
| `404 Not Found`    | Instituição financeira não encontrada |

***

### PUT /v1/webhooks/{idWebhook}

Atualiza a URL, o tipo de evento e a descrição de um webhook existente.

**Path Parameters:**

| Parâmetro   | Tipo | Descrição                |
| ----------- | ---- | ------------------------ |
| `idWebhook` | Int  | Identificador do webhook |

**Request:**

```bash
curl --request PUT \
  --url 'https://api-banking.barte.com/v1/webhooks/1' \
  --cert client.pem \
  --key client-key.pem \
  --header 'Authorization: Bearer {token}' \
  --header 'Content-Type: application/json' \
  --data '{
    "url": "https://meu-sistema.com.br/webhooks/kyc-v2",
    "eventType": "ACCOUNT_HOLDER_STATUS",
    "description": "Notificações de status de conta (v2)"
  }'
```

#### Campos — Request

| Campo         | Tipo   | Obrigatório | Validação                                                                                 |
| ------------- | ------ | ----------- | ----------------------------------------------------------------------------------------- |
| `url`         | String | Sim         | URL de destino. Ex: `https://meu-sistema.com.br/webhook`                                  |
| `eventType`   | String | Sim         | Enum: `CASH_IN`, `CASH_OUT`, `CASH_OUT_REFUND`, `ACCOUNT_STATUS`, `ACCOUNT_HOLDER_STATUS` |
| `description` | String | Não         | Nova descrição do webhook                                                                 |

**Response — 202 Accepted:**

```json
{
  "id": 1,
  "url": "https://meu-sistema.com.br/webhooks/kyc-v2",
  "eventType": "account_holder_status.update",
  "description": "Notificações de status de conta (v2)",
  "isActive": true
}
```

**Status Codes:**

| Status             | Descrição                      |
| ------------------ | ------------------------------ |
| `202 Accepted`     | Webhook atualizado com sucesso |
| `400 Bad Request`  | Dados inválidos                |
| `401 Unauthorized` | Token inválido ou expirado     |
| `403 Forbidden`    | Autoridade `PAYFAC` necessária |
| `404 Not Found`    | Webhook não encontrado         |

***

### PATCH /v1/webhooks/{idWebhook}/active

Ativa ou inativa um webhook. Somente webhooks ativos recebem notificações.

**Path Parameters:**

| Parâmetro   | Tipo | Descrição                |
| ----------- | ---- | ------------------------ |
| `idWebhook` | Int  | Identificador do webhook |

**Headers adicionais:**

| Header     | Obrigatório | Descrição                                 |
| ---------- | ----------- | ----------------------------------------- |
| `isActive` | Sim         | `true` para ativar, `false` para inativar |

**Request:**

```bash
curl --request PATCH \
  --url 'https://api-banking.barte.com/v1/webhooks/1/active' \
  --cert client.pem \
  --key client-key.pem \
  --header 'Authorization: Bearer {token}' \
  --header 'isActive: false'
```

**Response — 200 OK:** Sem corpo de resposta.

**Status Codes:**

| Status             | Descrição                                |
| ------------------ | ---------------------------------------- |
| `200 OK`           | Status do webhook atualizado com sucesso |
| `401 Unauthorized` | Token inválido ou expirado               |
| `403 Forbidden`    | Autoridade `PAYFAC` necessária           |
| `404 Not Found`    | Webhook não encontrado                   |

## Tipos de Evento

| Evento                         | Quando                          | Descrição                                                                                                                    |
| ------------------------------ | ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `account_status.update`        | Mudança de status da conta (v1) | Notificações de KYC via fluxo legado — ver [Eventos de Conta v1](/banking/api/webhooks/webhooks-v1.md)                       |
| `account_holder_status.update` | Mudança de status da conta (v2) | Notificações de KYC e biometria com detalhamento por sócio — ver [Eventos de Conta v2](/banking/api/webhooks/webhooks-v2.md) |
| `cash_in.update`               | Depósito na conta               | Notifica qualquer depósito feito para a conta                                                                                |
| `cash_out.update`              | Saque ou pagamento              | Notifica qualquer saque ou pagamento feito pela conta                                                                        |
| `cash_out.refund`              | Estorno na conta                | Notifica qualquer estorno que houver na conta                                                                                |

## Status de Pagamento

| Status     | Descrição                  | Ação recomendada                                      |
| ---------- | -------------------------- | ----------------------------------------------------- |
| `SUCCESS`  | Pagamento em processamento | Aguardar a conclusão do processamento                 |
| `FAILED`   | Pagamento falhou           | Verificar o motivo da falha e tomar a ação apropriada |
| `REFUNDED` | Pagamento estornado        | Verificar o estorno e tomar a ação apropriada         |

## Exemplos de Payload — Pagamentos

### Pagamento efetuado ou Saque

```json
{
  "id": "488cfff1-7b81-47cc-a68f-fcf6d0246a3e",
  "eventType": "cash_out.update",
  "amount": 0.01,
  "initiationType": "static_qrcode",
  "endToEndId": "E3168015120251236210953SF2OT9BB8",
  "status": "SUCCESS",
  "operationDate": "2025-08-27T00:00:00",
  "description": "",
  "errorReason": null,
  "creditParty": {
    "pixKey": "33439146812",
    "name": "Empresa Recebedora LTDA",
    "document": "12345678000199",
    "accountNumber": "987654",
    "accountType": "CACC",
    "branch": "0001"
  },
  "debitParty": {
    "accountNumber": "123456",
    "accountType": "CACC",
    "bankIspb": "87654321",
    "branch": "0001",
    "document": "98765432100",
    "name": "Cliente Pagador"
  }
}
```

### Depósito

```json
{
  "id": "8b8baece-7da7-4441-8826-fb507a481106",
  "eventType": "cash_in.update",
  "amount": 1000000,
  "initiationType": "static_qrcode",
  "endToEndId": "E3168015120251236210953SF2OT9BB8",
  "status": "SUCCESS",
  "operationDate": "2026-02-20T00:00:00",
  "description": "Payment simulation",
  "errorReason": null,
  "creditParty": {
    "pixKey": "d46fe074-c77c-4ef5-8831-7a6833cd2781",
    "name": "Cliente Recebedor",
    "document": "36186677000103",
    "accountNumber": "118802",
    "accountType": "TRAN",
    "branch": "1"
  },
  "debitParty": {
    "accountNumber": "4370771",
    "accountType": "CACC",
    "bankIspb": "30306294",
    "branch": "30",
    "document": "31680151000161",
    "name": "Cliente Pagador"
  }
}
```

### Estorno

```json
{
  "id": "804",
  "eventType": "cash_out.refund",
  "amount": 0.01,
  "initiationType": "static_qrcode",
  "endToEndId": "E3168015120251236210953SF2OT9BB8",
  "status": "REFUNDED",
  "operationDate": "2025-12-05T11:50:47",
  "description": null,
  "errorReason": "devolução solicitada pelo destinatário final",
  "creditParty": {
    "pixKey": "33541533854",
    "name": "Cliente Pagador",
    "document": "98765432100",
    "accountNumber": "123456",
    "accountType": "CACC",
    "branch": "0001"
  },
  "debitParty": {
    "accountNumber": "987654",
    "accountType": "CACC",
    "bankIspb": "12345678",
    "branch": "0001",
    "document": "12345678000199",
    "name": "Empresa Recebedora LTDA"
  }
}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.barte.com/banking/api/webhooks/webhooks.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.