> ## 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.
# Webhooks
> Como configurar e tratar webhooks para operações de Pix Indireto via BTG.
Webhooks são o principal mecanismo que o **Plugin de Pix Indireto (BTG)** usa para notificar você sobre eventos relacionados ao Pix em tempo real.
Em vez de depender de respostas síncronas, você recebe **callbacks assíncronos e orientados a eventos** sempre que ocorrem mudanças relevantes nas operações de Pix — como transferências, devoluções, reivindicações de chave ou eventos relacionados ao MED.
Esse modelo garante:
* Atualizações quase em tempo real
* Integrações desacopladas
* Conciliação confiável e rastreabilidade operacional
Os webhooks descritos nesta página aplicam-se atualmente ao **modelo de Pix Indireto via BTG**.
Os webhooks de Pix Direto podem diferir dependendo do modelo de conectividade e são documentados separadamente.
# Pré-requisitos
***
Antes de configurar os webhooks, certifique-se de ter:
* O Plugin de Pix Indireto configurado e em execução (consulte [Como funciona a participação indireta](/pt/midaz/plugins/pix/pix-overview))
* Um endpoint HTTPS pronto para receber requisições de webhook
* Compreensão básica do ciclo de vida de eventos do Pix e dos fluxos de transação
# Por que os webhooks são importantes no Pix
***
O Pix é um sistema assíncrono e multipartes.
Mesmo quando uma requisição de API é bem-sucedida, o **estado final de uma transação só é confirmado posteriormente**, após a liquidação e a confirmação da contraparte.
Os webhooks permitem que seu sistema:
* Acompanhe o **status autoritativo da transação**
* Reaja a **devoluções, estornos e eventos de MED**
* Mantenha a **consistência contábil e operacional**
* Reduza o polling e a sobrecarga operacional
# Tipos de evento
***
Você recebe eventos agrupados por **fluxo** e **entidade**, alinhados aos domínios do BACEN (Banco Central do Brasil).
| Fluxo | Entidade | Descrição |
| -------- | ---------------------- | ---------------------------------------------------------------------------------------------------- |
| DICT | CLAIM | Eventos de portabilidade e reivindicação de propriedade de chave Pix |
| DICT | INFRACTION\_REPORT | Relatos de infração do MED (Mecanismo Especial de Devolução) e ciclo de vida de disputas |
| DICT | REFUND | Eventos de solicitação de devolução do MED |
| DICT | FUNDS\_RECOVERY | Mudanças de status da entidade Recuperação de Fundos do MED 2.0 (com persistência em banco de dados) |
| DICT | FUNDS\_RECOVERY\_EVENT | Eventos do ciclo de vida da Recuperação de Fundos do MED 2.0 (repasse direto) |
| TRANSFER | CASHIN | Atualizações de status de pagamentos Pix recebidos |
| TRANSFER | CASHOUT | Atualizações de status de pagamentos Pix enviados |
| REFUND | CASHIN | Atualizações de status de devoluções Pix recebidas |
| REFUND | CASHOUT | Atualizações de status de devoluções Pix enviadas |
Cada evento reflete uma **transição de estado** no ecossistema Pix e deve ser tratado como a fonte da verdade.
As duas entidades do **MED 2.0** comportam-se de forma diferente: `FUNDS_RECOVERY` é emitida após o plugin atualizar seu registro local, enquanto `FUNDS_RECOVERY_EVENT` é um repasse direto dos eventos de ciclo de vida do BTG, sem atualização no banco de dados. Consulte [MED 2.0 — Recuperação de Fundos](/pt/midaz/plugins/pix/indirect/indirect-pix-med-2-funds-recovery) para o fluxo completo.
O **DICT** (Diretório de Identificadores de Contas Transacionais) é o diretório do BACEN que gerencia as chaves Pix e operações relacionadas, como reivindicações, infrações e devoluções.
# Configuração de webhooks
***
Você habilita os webhooks configurando **URLs de destino** e selecionando quais tipos de evento seu sistema deve receber.
## Variáveis de ambiente
***
Você pode configurar os endpoints de webhook em nível de **entidade**, **fluxo** ou **global**.
| Fluxo | Entidade | Variável de URL em nível de entidade |
| -------- | ------------------ | ------------------------------------ |
| DICT | CLAIM | `WEBHOOK_DICT_CLAIM_URL` |
| DICT | INFRACTION\_REPORT | `WEBHOOK_DICT_INFRACTION_REPORT_URL` |
| DICT | REFUND | `WEBHOOK_DICT_REFUND_URL` |
| TRANSFER | CASHIN | `WEBHOOK_TRANSFER_CASHIN_URL` |
| TRANSFER | CASHOUT | `WEBHOOK_TRANSFER_CASHOUT_URL` |
| REFUND | CASHIN | `WEBHOOK_REFUND_CASHIN_URL` |
| REFUND | CASHOUT | `WEBHOOK_REFUND_CASHOUT_URL` |
Cada fluxo também tem uma **URL em nível de fluxo** que se aplica a todas as suas entidades quando nenhuma URL em nível de entidade está definida: `WEBHOOK_DICT_URL`, `WEBHOOK_TRANSFER_URL` e `WEBHOOK_REFUND_URL`.
## Prioridade de resolução de URL
***
Quando várias URLs estão configuradas, o sistema as resolve na seguinte ordem:
1. **URL em nível de entidade**
Exemplo: `WEBHOOK_DICT_CLAIM_URL`
2. **URL em nível de fluxo**
Exemplo: `WEBHOOK_DICT_URL`
3. **URL padrão**
`WEBHOOK_DEFAULT_URL`
Isso oferece controle de roteamento granular sem duplicar a infraestrutura.
# Formato da requisição
***
## Cabeçalhos
***
Toda requisição de webhook inclui cabeçalhos padronizados para rastreabilidade e segurança.
| Cabeçalho | Descrição |
| ----------------- | ----------------------------------------------- |
| `Content-Type` | `application/json` |
| `X-Request-ID` | Identificador único da requisição |
| `X-Entity-Type` | Entidade do evento (ex.: `INFRACTION_REPORT`) |
| `X-Flow-Type` | Domínio de origem (ex.: `DICT`) |
| `Idempotency-Key` | Identificador único do evento para deduplicação |
## Estrutura do corpo
***
```json theme={null}
{
"entityType": "INFRACTION_REPORT",
"flowType": "DICT",
"payload": {
...
}
}
```
| Campo | Descrição |
| ------------ | --------------------------- |
| `entityType` | Entidade do evento |
| `flowType` | Domínio do Pix |
| `payload` | Dados específicos do evento |
O schema do payload varia conforme o tipo de evento, mas sempre representa uma **mudança de estado**.
# Respostas e comportamento de retentativa
***
## Resposta esperada
***
Seu endpoint deve retornar um status **HTTP 2xx** para confirmar a entrega bem-sucedida.
| Resposta | Resultado |
| -------- | ------------------------- |
| 2xx | Entregue com sucesso |
| Não-2xx | Reenviado automaticamente |
## Estratégia de retentativa
***
Entregas que falham são reenviadas automaticamente usando **backoff exponencial**:
| Tentativa | Atraso |
| --------- | ---------- |
| 1 | 1 segundo |
| 2 | 2 segundos |
| 3 | 4 segundos |
**Padrões**
* Máximo de retentativas: 3
* Timeout por requisição: 30 segundos
Após todas as retentativas falharem, o evento é movido para uma **fila de falhas** para acompanhamento operacional.
### Configurações personalizadas de retentativa
Retentativas e timeouts podem ser personalizados por evento:
```bash theme={null}
WEBHOOK_DICT_INFRACTION_REPORT_MAX_RETRIES=5
WEBHOOK_DICT_INFRACTION_REPORT_REQUEST_TIMEOUT=60s
```
## Proteção por circuit breaker
***
Para evitar falhas em cascata, a entrega de webhooks é protegida por um **circuit breaker**.
Quando o Plugin de Pix detecta **falhas repetidas de entrega** (normalmente respostas `5xx` consecutivas ou timeouts), ele **pausa temporariamente as chamadas de webhook** para o endpoint afetado.
Após um período de espera configurável, o sistema realiza **tentativas controladas de retentativa** para verificar se o endpoint se recuperou.
Assim que respostas bem-sucedidas são detectadas, a entrega normal é retomada automaticamente.
Esse mecanismo garante:
* Proteção contra endpoints sobrecarregados ou instáveis
* Recuperação suave sem intervenção manual
* Maior estabilidade geral do sistema em ambientes de produção
O comportamento do circuit breaker funciona em conjunto com as retentativas e o backoff exponencial, adicionando uma camada extra de segurança para a entrega de webhooks.
## Erros de transporte e eventos órfãos
***
Uma tentativa de entrega pode falhar na camada de transporte (conexão recusada, falha de DNS, erro de handshake TLS) antes que qualquer status HTTP seja retornado. Essas falhas são **persistidas como eventos órfãos** em vez de perdidas, de modo que permanecem visíveis para acompanhamento operacional e reprocessamento, em vez de desaparecerem silenciosamente.
Ao tratar eventos de devolução, observe que as buscas de transferência para cash-in e cash-out de `REFUND` foram expandidas para resolver corretamente em ambas as direções — garanta que seu consumidor indexe as devoluções por `originalEndToEndId` em vez de assumir um único caminho de busca.
# Relatórios de transações internas (intra-PSP)
***
Transferências intra-PSP (P2P) são liquidadas internamente e nunca chegam ao BTG para liquidação, mas ainda são reportadas ao BACEN por meio da abstração **TRCK002**. O BTG confirma o status do relatório por meio de um webhook **CAMT025** que carrega a entidade `PixInternalTransactionsReport`.
| Campo | Descrição |
| -------------------------------- | ------------------------------------------------------------------- |
| `pactualId` | Identificador do relatório atribuído pelo BTG |
| `clientRequestId` | Sua chave de idempotência, enviada durante a submissão do relatório |
| `entity` | Sempre `PixInternalTransactionsReport` |
| `status` | `PROCESSING`, `CONFIRMED` ou `ERROR` |
| `errorCode` / `errorDescription` | Preenchidos quando `status = ERROR` |
O plugin atualiza o status do relatório e, na conclusão ou falha, emite os eventos de saída intra-PSP padrão (`cashout.completed`/`cashout.failed`, `cashin.completed` e os equivalentes de devolução). Para o fluxo interno completo, consulte [Transferências intra-PSP](/pt/midaz/plugins/pix/indirect/indirect-pix-intra-psp).
# Boas práticas
***
| Prática | Por que é importante |
| ------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| **Ignore campos desconhecidos** | Permanece compatível com o futuro à medida que novos campos são adicionados |
| **Processamento idempotente** | Use `Idempotency-Key` para evitar processar duplicatas |
| **Confirmação rápida** | Retorne `202 Accepted` e processe de forma assíncrona |
| **Processamento assíncrono** | Evite bloquear a thread do webhook |
| **Trate a compressão** | Payloads >1KB são compactados com gzip. Verifique o cabeçalho `Content-Encoding` e descompacte conforme necessário |
# Exemplos de eventos
***
A seguir estão exemplos representativos de payloads de webhook que você recebe do Plugin de Pix Indireto. Expanda cada entrada para ver seu payload.
Eventos de ciclo de vida de propriedade ou portabilidade. Use-os para acompanhar disputas de chave Pix entre instituições.
```json theme={null}
{
"entityType": "CLAIM",
"flowType": "DICT",
"payload": {
"id": "claim-7f8a9b2c-1234-5678-abcd-ef0123456789",
"key": "+5511999998888",
"keyType": "PHONE",
"claimType": "PORTABILITY",
"claimer": {
"ispb": "12345678",
"name": "Banco Exemplo S.A."
},
"donor": {
"ispb": "87654321",
"name": "Outra Instituição S.A."
},
"status": "CONFIRMED",
"createdAt": "2024-01-15T10:30:00Z",
"updatedAt": "2024-01-15T14:45:00Z"
}
}
```
Eventos de sinalização de disputa e fraude alinhados às regras do MED do BACEN.
```json theme={null}
{
"entityType": "INFRACTION_REPORT",
"flowType": "DICT",
"payload": {
"id": "infraction-3e4f5a6b-7890-1234-cdef-567890abcdef",
"endToEndId": "E12345678202401151030abcdefghij12",
"infractionType": "FRAUD",
"reportedBy": {
"ispb": "12345678",
"name": "Banco Exemplo S.A."
},
"reportedAgainst": {
"ispb": "87654321",
"name": "Outra Instituição S.A."
},
"status": "OPEN",
"analysisResult": null,
"createdAt": "2024-01-15T10:30:00Z",
"updatedAt": "2024-01-15T10:30:00Z"
}
}
```
Solicitações e decisões de devolução relacionadas a casos de MED.
```json theme={null}
{
"entityType": "REFUND",
"flowType": "DICT",
"payload": {
"id": "refund-9a8b7c6d-5432-1098-fedc-ba0987654321",
"endToEndId": "E12345678202401151030abcdefghij12",
"infractionId": "infraction-3e4f5a6b-7890-1234-cdef-567890abcdef",
"refundAmount": 150.00,
"refundReason": "FRAUD",
"status": "REQUESTED",
"requestedBy": {
"ispb": "12345678",
"name": "Banco Exemplo S.A."
},
"createdAt": "2024-01-16T09:00:00Z",
"updatedAt": "2024-01-16T09:00:00Z"
}
}
```
Mudanças de status da entidade Recuperação de Fundos. O plugin atualiza seu registro local antes de encaminhar a entidade completa.
```json theme={null}
{
"entityType": "FUNDS_RECOVERY",
"flowType": "DICT",
"payload": {
"id": "91d65e98-97c0-4b0f-b577-73625da1f9fc",
"externalId": "ca1b9c01-ff9e-4a58-90ab-d31512e15ce0",
"accountId": "01989f9e-6508-79f8-9540-835be49fbd0d",
"status": "CREATED",
"rootTransactionId": "E9999901012341234123412345678900",
"situationType": "SCAM",
"reporterParticipant": "99999010",
"contactInformation": {},
"reportDetails": "Details to help receiving participants",
"createdAt": "2020-01-17T10:00:00.000Z",
"updatedAt": "2020-01-17T10:00:00.000Z"
}
}
```
Os eventos de ciclo de vida chegam como `entityType: FUNDS_RECOVERY_EVENT` (repasse direto, sem atualização no banco de dados), com valores de `event` como `FUNDS_RECOVERY_ANALYSED` e `FUNDS_RECOVERY_COMPLETED`.
Eventos de transferência Pix recebida e enviada.
**Cash-in (transferência recebida):**
```json theme={null}
{
"entityType": "CASHIN",
"flowType": "TRANSFER",
"payload": {
"id": "transfer-1a2b3c4d-5678-90ab-cdef-1234567890ab",
"endToEndId": "E12345678202401151030abcdefghij12",
"amount": 250.00,
"payer": {
"ispb": "87654321",
"name": "João Silva",
"cpfCnpj": "12345678901"
},
"payee": {
"ispb": "12345678",
"name": "Maria Santos",
"cpfCnpj": "98765432100",
"accountNumber": "12345-6"
},
"status": "SETTLED",
"createdAt": "2024-01-15T10:30:00Z",
"settledAt": "2024-01-15T10:30:05Z"
}
}
```
**Cash-out (transferência enviada):**
```json theme={null}
{
"entityType": "CASHOUT",
"flowType": "TRANSFER",
"payload": {
"id": "transfer-2b3c4d5e-6789-01bc-def0-2345678901bc",
"endToEndId": "E87654321202401151045zyxwvutsrqp98",
"amount": 500.00,
"payer": {
"ispb": "12345678",
"name": "Maria Santos",
"cpfCnpj": "98765432100",
"accountNumber": "12345-6"
},
"payee": {
"ispb": "87654321",
"name": "Empresa ABC Ltda",
"cpfCnpj": "12345678000199"
},
"status": "SETTLED",
"createdAt": "2024-01-15T10:45:00Z",
"settledAt": "2024-01-15T10:45:03Z"
}
}
```
Eventos de liquidação de devolução para transações Pix.
**Refund cash-in (recebendo uma devolução):**
```json theme={null}
{
"entityType": "CASHIN",
"flowType": "REFUND",
"payload": {
"id": "refund-4d5e6f7g-8901-23cd-ef01-4567890123cd",
"originalEndToEndId": "E87654321202401151045zyxwvutsrqp98",
"refundEndToEndId": "D12345678202401161000refund123456",
"amount": 500.00,
"reason": "CUSTOMER_REQUEST",
"status": "SETTLED",
"createdAt": "2024-01-16T10:00:00Z",
"settledAt": "2024-01-16T10:00:02Z"
}
}
```
**Refund cash-out (enviando uma devolução):**
```json theme={null}
{
"entityType": "CASHOUT",
"flowType": "REFUND",
"payload": {
"id": "refund-5e6f7g8h-9012-34de-f012-5678901234de",
"originalEndToEndId": "E12345678202401151030abcdefghij12",
"refundEndToEndId": "D87654321202401161015refund789012",
"amount": 250.00,
"reason": "OPERATIONAL_FLAW",
"status": "SETTLED",
"createdAt": "2024-01-16T10:15:00Z",
"settledAt": "2024-01-16T10:15:04Z"
}
}
```
# Conclusão principal
***
Os webhooks **não são opcionais** nas operações de Pix Indireto.
Eles são o **canal autoritativo** para o estado da transação, devoluções e tratamento de disputas.
Uma implementação correta de webhooks garante:
* Conciliação precisa
* Conformidade regulatória
* Resiliência operacional
* Experiência previsível para o cliente
Para ambientes de produção, projete sempre os consumidores de webhook como **sistemas idempotentes, assíncronos e observáveis**.
# Próximos passos
***
Agora que você entende como os webhooks funcionam no Pix Indireto, explore estes tópicos relacionados:
* [Principais domínios do Pix: transferências](/pt/midaz/plugins/pix/main-domains-transactions) - Aprofundamento nas operações de transferência
* [Principais domínios do Pix: DICT](/pt/midaz/plugins/pix/main-domains-dict) - Compreensão das operações do DICT e do gerenciamento de chaves
* [Principais domínios do Pix: MED](/pt/midaz/plugins/pix/main-domains-med) - Tratamento de disputas e devoluções do MED
* [MED 2.0 — Recuperação de Fundos](/pt/midaz/plugins/pix/indirect/indirect-pix-med-2-funds-recovery) - Recuperação de fraude entre contas e seus webhooks
* [Transferências intra-PSP](/pt/midaz/plugins/pix/indirect/indirect-pix-intra-psp) - Liquidação interna P2P e relatórios TRCK002
* [Referência da API](/pt/reference/midaz/plugins/indirect-pix/create-entry) — Documentação completa da API para operações de DICT, Reivindicações, Transações, QR Codes e MED