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. Você não depende de respostas síncronas. Em vez disso, você recebe callbacks assíncronos e orientados a eventos quando ocorrem mudanças relevantes nas operações de Pix — transferências, devoluções, reivindicações de chave ou eventos de MED. Esse modelo oferece a você:

Atualizações quase em tempo real
Integrações desacopladas
Conciliação confiável e rastreabilidade operacional

Estes webhooks aplicam-se somente ao modelo de Pix Indireto via BTG.Os webhooks de Pix Direto podem diferir conforme o modelo de conectividade. Uma página à parte os documenta.

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. Uma requisição de API pode ser bem-sucedida antes de a transação alcançar seu estado final. O sistema confirma esse estado mais tarde, 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. Trate cada evento como a fonte da verdade.

As duas entidades do MED 2.0 comportam-se de forma diferente. O plugin emite FUNDS_RECOVERY após atualizar seu registro local. 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

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 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 para todas as suas entidades. O plugin a usa quando nenhuma URL em nível de entidade existe: 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 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 e sem infraestrutura duplicada.

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

O plugin reenvia automaticamente as entregas que falham com 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 plugin move o evento para uma fila de mensagens falhas para acompanhamento operacional.

Configurações personalizadas de retentativa

Você pode personalizar as retentativas 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 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. Quando o endpoint volta a retornar respostas bem-sucedidas, o plugin retoma a entrega normal automaticamente. Esse mecanismo oferece a você:

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 circuit breaker funciona em conjunto com as retentativas e o backoff exponencial. Ele adiciona uma camada extra de segurança para a entrega de webhooks.

Erros de transporte e eventos órfãos

Quando o plugin recebe um webhook de devolução, ele busca a transferência original ao longo da cadeia cash-in → cash-out. Se nenhuma fonte 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, de modo que o registro permanece visível para conciliação e acompanhamento. Se uma busca de fonte falhar na camada de transporte, o plugin ignora essa fonte e continua. Quando nenhuma fonte corresponde — por uma ausência limpa ou um erro de transporte descartado — o plugin registra a devolução como órfã. O plugin só aborta quando a ponte de busca de transferências não está configurada. originalEndToEndId é a chave canônica para todas as buscas de devolução. O plugin resolve as devoluções a partir de ambas as direções, cash-in → refund e cash-out → refund, com esse campo. Indexe sempre as devoluções por originalEndToEndId (o ID de ponta a ponta da transferência original), não por um único caminho de busca específico de direção.

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 o plugin ainda as reporta 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 quando o webhook de relatório CAMT025 confirma ou falha. Os webhooks de saída são emitidos antes, quando a transferência intra-PSP é liquidada: cashin.completed para o lado de cash-in e cashout.completed ou cashout.failed para o lado de cash-out. 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 oferece a você:

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

Visão geral

Lerian SPI — mensageria nativa

JD — interface (Pix direto)

BTG — interface (Pix indireto)

Webhooks

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

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