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)
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 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:

URL em nível de entidade Exemplo: WEBHOOK_DICT_CLAIM_URL
URL em nível de fluxo Exemplo: WEBHOOK_DICT_URL
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

{
  "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:

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.

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.

DICT claim

Eventos de ciclo de vida de propriedade ou portabilidade. Use-os para acompanhar disputas de chave Pix entre instituições.

{
  "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"
  }
}

DICT infraction report (MED)

Eventos de sinalização de disputa e fraude alinhados às regras do MED do BACEN.

{
  "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"
  }
}

DICT refund (MED)

Solicitações e decisões de devolução relacionadas a casos de MED.

{
  "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"
  }
}

DICT funds recovery (MED 2.0)

Mudanças de status da entidade Recuperação de Fundos. O plugin atualiza seu registro local antes de encaminhar a entidade completa.

{
  "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.

Transfer cash-in and cash-out

Eventos de transferência Pix recebida e enviada.Cash-in (transferência recebida):

{
  "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):

{
  "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"
  }
}

Refund cash-in and cash-out

Eventos de liquidação de devolução para transações Pix.Refund cash-in (recebendo uma devolução):

{
  "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):

{
  "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 - Aprofundamento nas operações de transferência
Principais domínios do Pix: DICT - Compreensão das operações do DICT e do gerenciamento de chaves
Principais domínios do Pix: MED - Tratamento de disputas e devoluções do MED
MED 2.0 — Recuperação de Fundos - Recuperação de fraude entre contas e seus webhooks
Transferências intra-PSP - Liquidação interna P2P e relatórios TRCK002
Referência da API — Documentação completa da API para operações de DICT, Reivindicações, Transações, QR Codes e MED

​Pré-requisitos

​Por que os webhooks são importantes no Pix

​Tipos de evento

​Configuração de webhooks

​Variáveis de ambiente

​Prioridade de resolução de URL

​Formato da requisição

​Cabeçalhos

​Estrutura do corpo

​Respostas e comportamento de retentativa

​Resposta esperada

​Estratégia de retentativa

​Configurações personalizadas de retentativa

​Proteção por circuit breaker

​Erros de transporte e eventos órfãos

​Relatórios de transações internas (intra-PSP)

​Boas práticas

​Exemplos de eventos

​Conclusão principal

​Próximos passos

Pré-requisitos

Por que os webhooks são importantes no Pix

Tipos de evento

Configuração de webhooks

Variáveis de ambiente

Prioridade de resolução de URL

Formato da requisição

Cabeçalhos

Estrutura do corpo

Respostas e comportamento de retentativa

Resposta esperada

Estratégia de retentativa

Configurações personalizadas de retentativa

Proteção por circuit breaker

Erros de transporte e eventos órfãos

Relatórios de transações internas (intra-PSP)

Boas práticas

Exemplos de eventos

Conclusão principal

Próximos passos