> ## 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
> Configure e consuma os webhooks do Plugin Pix Indireto via BTG: tipos de evento de reivindicação DICT, infração, devolução, transferência e MED 2.0, com assinatura HMAC.
Os webhooks são o mecanismo principal que o **Plugin Pix Indireto (BTG)** usa para avisar você sobre eventos de Pix em tempo real.
Você recebe **callbacks assíncronos, orientados a eventos**, quando ocorrem mudanças nas operações Pix: transferências, devoluções, reivindicações de chave ou eventos de MED.
Esses webhooks se aplicam apenas ao **modelo de Pix Indireto via BTG**.
Os webhooks do Pix Direto podem variar conforme o modelo de conectividade. Uma página à parte documenta esses webhooks.
# Pré-requisitos
***
Antes de configurar os webhooks, confirme que você tem:
* O Plugin Pix Indireto configurado e em execução (veja [Como funciona a participação indireta](/pt/interfaces/pix/pix-overview))
* Um endpoint HTTPS pronto para receber as requisições de webhook
* Entendimento básico do ciclo de vida dos eventos Pix e dos fluxos de transação
# O que os webhooks oferecem
***
Os webhooks **não são opcionais** nas operações de Pix Indireto.
O Pix é um sistema assíncrono e com várias partes.
Uma requisição de API pode ter sucesso antes de a transação chegar ao seu **estado final**. O sistema confirma esse estado depois, 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 do ledger e a consistência 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 de reivindicação de posse de chave Pix |
| DICT | INFRACTION\_REPORT | Relatos de infração do MED (Mecanismo Especial de Devolução) e ciclo de vida da disputa |
| DICT | REFUND | Eventos de solicitação de devolução do MED |
| DICT | FUNDS\_RECOVERY | Mudanças de status da entidade de Recuperação de Fundos do MED 2.0 (com registro em banco) |
| DICT | FUNDS\_RECOVERY\_EVENT | Eventos de ciclo de vida da Recuperação de Fundos do MED 2.0 (repasse) |
| TRANSFER | CASHIN | Atualizações de status de pagamento Pix recebido |
| TRANSFER | CASHOUT | Atualizações de status de pagamento Pix enviado |
| REFUND | CASHIN | Atualizações de status de devolução Pix recebida |
| REFUND | CASHOUT | Atualizações de status de devolução Pix enviada |
Cada evento reflete uma **transição de estado** no ecossistema Pix. Trate cada evento como a fonte da verdade.
As duas entidades do **MED 2.0** se comportam de formas diferentes. O plugin emite `FUNDS_RECOVERY` depois de atualizar o registro local. `FUNDS_RECOVERY_EVENT` é um repasse dos eventos de ciclo de vida do BTG, sem atualização no banco. Veja [MED 2.0 — Recuperação de Fundos](/pt/interfaces/pix-btg/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 as operações relacionadas, como reivindicações, infrações e devoluções.
# Configuração de webhooks
***
Para habilitar os webhooks, configure as **URLs de destino** e selecione quais tipos de evento seu sistema recebe.
## Variáveis de ambiente
***
Você pode configurar os endpoints de webhook no nível de **entidade**, de **fluxo** ou **global**.
| Fluxo | Entidade | Variável de URL no nível da 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 no nível do fluxo** para todas as suas entidades. O plugin a usa quando não existe URL no nível da entidade: `WEBHOOK_DICT_URL`, `WEBHOOK_TRANSFER_URL` e `WEBHOOK_REFUND_URL`.
## Prioridade de resolução de URL
***
Quando você configura várias URLs, o plugin as resolve nesta ordem:
1. **URL no nível da entidade**
Exemplo: `WEBHOOK_DICT_CLAIM_URL`
2. **URL no nível do fluxo**
Exemplo: `WEBHOOK_DICT_URL`
3. **URL padrão**
`WEBHOOK_DEFAULT_URL`
# Formato da requisição
***
## Headers
***
Toda requisição de webhook inclui headers padronizados para rastreabilidade e segurança.
| Header | Descrição |
| ----------------- | ----------------------------------------------------- |
| `Content-Type` | `application/json` |
| `X-Request-ID` | Identificador único da requisição |
| `X-Entity-Type` | Entidade do evento (por exemplo, `INFRACTION_REPORT`) |
| `X-Flow-Type` | Domínio de origem (por exemplo, `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 nova tentativa
***
## Resposta esperada
***
Seu endpoint deve retornar um status **HTTP 2xx** para confirmar a entrega.
| Resposta | Resultado |
| ----------- | ------------------------- |
| 2xx | Entregue com sucesso |
| Fora de 2xx | Nova tentativa automática |
## Estratégia de novas tentativas
***
O plugin repete automaticamente as entregas que falham, com **backoff exponencial**:
| Tentativa | Espera |
| --------- | ---------- |
| 1 | 1 segundo |
| 2 | 2 segundos |
| 3 | 4 segundos |
**Padrões**
* Máximo de novas tentativas: 3
* Timeout por requisição: 30 segundos
Depois que todas as tentativas falham, o plugin move o evento para uma **dead-letter queue** para acompanhamento operacional.
### Configurações de nova tentativa customizadas
Você pode customizar as novas tentativas e os timeouts por evento:
```bash theme={null}
WEBHOOK_DICT_INFRACTION_REPORT_MAX_RETRIES=5
WEBHOOK_DICT_INFRACTION_REPORT_REQUEST_TIMEOUT=60s
```
## Proteção por circuit breaker
***
Um **circuit breaker** protege a entrega de webhooks e evita falhas em cascata.
Quando o Plugin Pix detecta **falhas repetidas de entrega** (normalmente respostas `5xx` consecutivas ou timeouts), ele **pausa temporariamente as chamadas de webhook** para o endpoint afetado.
Depois de um período de espera configurável, o sistema tenta o endpoint de novo para checar se ele se recuperou.
Quando o endpoint volta a responder com sucesso, o plugin retoma a entrega normal automaticamente.
O circuit breaker funciona junto com as novas tentativas e o backoff exponencial.
## Erros de transporte e eventos órfãos
***
Quando o plugin recebe um webhook de devolução, ele procura a transferência original ao longo da cadeia cash-in → cash-out. Se nenhuma origem local corresponder, o plugin persiste a devolução como um **registro órfão** para a auditabilidade do BACEN. Ele não descarta a devolução, então o registro continua visível para conciliação e acompanhamento. Se a consulta de uma origem falhar na camada de transporte, o plugin pula essa origem e continua. Quando nenhuma origem é resolvida (por uma ausência real ou por um erro de transporte engolido), o plugin registra a devolução como órfã. O plugin aborta apenas se você não configurar a ponte de consulta de transferências.
`originalEndToEndId` é a chave canônica de todas as consultas de devolução. O plugin resolve devoluções nos dois sentidos, cash-in → devolução e cash-out → devolução, com esse campo. Sempre indexe as devoluções por `originalEndToEndId` (o ID end-to-end da transferência original), não por um único caminho de consulta específico de um sentido.
# Relatórios de transações internas (intra-PSP)
***
O plugin liquida as transferências intra-PSP (P2P) internamente. Elas nunca chegam ao BTG para liquidação, mas mesmo assim o plugin as reporta ao BACEN pela abstração **TRCK002**. O BTG confirma o status do relatório por 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 no envio 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 quando o webhook de relatório CAMT025 confirma ou falha. Os webhooks de saída disparam antes, quando a transferência intra-PSP liquida: `cashin.completed` para a perna de cash-in e `cashout.completed` ou `cashout.failed` para a perna de cash-out. Para o fluxo interno completo, veja [Transferências intra-PSP](/pt/interfaces/pix-btg/indirect-pix-intra-psp).
# Boas práticas
***
| Prática | Por que importa |
| ------------------------------- | ----------------------------------------------------------------------------------------------------- |
| **Ignore campos desconhecidos** | Continue compatível com versões futuras conforme 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 comprimidos com gzip. Cheque o header `Content-Encoding` e descomprima conforme ele |
# Exemplos de evento
***
Expanda cada item para ver um payload de exemplo daquele tipo de evento.
Eventos de ciclo de vida de posse ou de 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 de 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 de Recuperação de Fundos. O plugin atualiza o 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, sem atualização no banco), 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 de transações Pix.
**Cash-in de devolução (receber 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"
}
}
```
**Cash-out de devolução (enviar 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"
}
}
```
# Próximos passos
***
* [Domínios principais do Pix: transferências](/pt/interfaces/pix/main-domains-transactions): Operações de transferência em detalhe
* [Domínios principais do Pix: DICT](/pt/interfaces/pix/main-domains-dict): Entenda as operações do DICT e a gestão de chaves
* [Domínios principais do Pix: MED](/pt/interfaces/pix/main-domains-med): Tratamento de disputa e devolução do MED
* [MED 2.0 — Recuperação de Fundos](/pt/interfaces/pix-btg/indirect-pix-med-2-funds-recovery): Recuperação de fraude entre contas e seus webhooks
* [Transferências intra-PSP](/pt/interfaces/pix-btg/indirect-pix-intra-psp): Liquidação P2P interna e reporte TRCK002
* [Referência da API](/pt/reference/interfaces/pix-btg/create-entry): Documentação completa da API para DICT, Reivindicações, Transações, QR Codes e operações de MED