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

URL no nível da entidade Exemplo: WEBHOOK_DICT_CLAIM_URL
URL no nível do fluxo Exemplo: WEBHOOK_DICT_URL
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

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

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.

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.

Reivindicação DICT

Eventos de ciclo de vida de posse ou de 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"
  }
}

Relato de infração DICT (MED)

Eventos de sinalização de disputa e de 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"
  }
}

Devolução DICT (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"
  }
}

Recuperação de fundos DICT (MED 2.0)

Mudanças de status da entidade de Recuperação de Fundos. O plugin atualiza o 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, sem atualização no banco), com valores de event como FUNDS_RECOVERY_ANALYSED e FUNDS_RECOVERY_COMPLETED.

Cash-in e cash-out de transferência

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

Cash-in e cash-out de devolução

Eventos de liquidação de devolução de transações Pix.Cash-in de devolução (receber 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"
  }
}

Cash-out de devolução (enviar 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"
  }
}

Próximos passos

Domínios principais do Pix: transferências: Operações de transferência em detalhe
Domínios principais do Pix: DICT: Entenda as operações do DICT e a gestão de chaves
Domínios principais do Pix: MED: Tratamento de disputa e devolução do MED
MED 2.0 — Recuperação de Fundos: Recuperação de fraude entre contas e seus webhooks
Transferências intra-PSP: Liquidação P2P interna e reporte TRCK002
Referência da API: Documentação completa da API para DICT, Reivindicações, Transações, QR Codes e operações de MED

​Pré-requisitos

​O que os webhooks oferecem

​Tipos de evento

​Configuração de webhooks

​Variáveis de ambiente

​Prioridade de resolução de URL

​Formato da requisição

​Headers

​Estrutura do corpo

​Respostas e comportamento de nova tentativa

​Resposta esperada

​Estratégia de novas tentativas

​Configurações de nova tentativa customizadas

​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 evento

​Próximos passos

Pré-requisitos

O que os webhooks oferecem

Tipos de evento

Configuração de webhooks

Variáveis de ambiente

Prioridade de resolução de URL

Formato da requisição

Headers

Estrutura do corpo

Respostas e comportamento de nova tentativa

Resposta esperada

Estratégia de novas tentativas

Configurações de nova tentativa customizadas

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 evento

Próximos passos