Webhooks são o mecanismo principal que o Plugin 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 orientados a eventos sempre que mudanças relevantes ocorrem nas operações Pix — como transferências, devoluções, reivindicações de chave ou eventos relacionados ao MED. Este modelo garante:

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

Os webhooks descritos nesta página atualmente se aplicam ao modelo de Pix Indireto via BTG.Webhooks do Pix Direto podem diferir dependendo do modelo de conectividade e são documentados separadamente.

Pré-requisitos

Antes de configurar webhooks, certifique-se de ter:

O Plugin Pix Indireto configurado e em execução (veja Como a participação indireta funciona)
Um endpoint HTTPS pronto para receber requisições de webhook
Entendimento básico do ciclo de vida de eventos Pix e fluxos de transação

Por que webhooks são importantes no Pix

O Pix é um sistema assíncrono e multipartícipe. Mesmo quando uma requisição à API tem sucesso, o estado final de uma transação só é confirmado depois, após liquidação e confirmação da contraparte. Webhooks permitem que seu sistema:

Rastreie o status autoritativo da transação
Reaja a devoluções, estornos e eventos do MED
Mantenha consistência do ledger e operacional
Reduza polling e sobrecarga operacional

Tipos de evento

Você recebe eventos agrupados por fluxo e entidade, alinhados com os 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	Relatórios de infração MED (Mecanismo Especial de Devolução) e ciclo de vida de disputas
DICT	REFUND	Eventos de solicitação de devolução MED
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 e deve ser tratado como a fonte da verdade.

DICT (Diretório de Identificadores de Contas Transacionais) é o diretório do BACEN que gerencia chaves Pix e operações relacionadas como reivindicações, infrações e devoluções.

Configuração de webhooks

Você habilita webhooks configurando URLs de destino e selecionando quais tipos de evento seu sistema deve receber.

Variáveis de ambiente

Você pode configurar endpoints de webhook em nível de entidade, fluxo ou global.

Fluxo	Entidade	URL da Entidade	URL do Módulo
DICT	CLAIM	`WEBHOOK_DICT_CLAIM_URL`	`WEBHOOK_DICT_URL`
DICT	INFRACTION_REPORT	`WEBHOOK_DICT_INFRACTION_REPORT_URL`	`WEBHOOK_DICT_URL`
DICT	REFUND	`WEBHOOK_DICT_REFUND_URL`	`WEBHOOK_DICT_URL`
TRANSFER	CASHIN	`WEBHOOK_TRANSFER_CASHIN_URL`	`WEBHOOK_TRANSFER_URL`
TRANSFER	CASHOUT	`WEBHOOK_TRANSFER_CASHOUT_URL`	`WEBHOOK_TRANSFER_URL`
REFUND	CASHIN	`WEBHOOK_REFUND_CASHIN_URL`	`WEBHOOK_REFUND_URL`
REFUND	CASHOUT	`WEBHOOK_REFUND_CASHOUT_URL`	`WEBHOOK_REFUND_URL`

Prioridade de resolução de URL

Quando múltiplas 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 granular de roteamento sem duplicar infraestrutura.

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 (ex.: `INFRACTION_REPORT`)
`X-Flow-Type`	Domínio de origem (ex.: `DICT`)
`Idempotency-Key`	Identificador único do evento para deduplicação

Estrutura do body

{
  "entityType": "INFRACTION_REPORT",
  "flowType": "DICT",
  "payload": {
    ...
  }
}

Campo	Descrição
`entityType`	Entidade do evento
`flowType`	Domínio Pix
`payload`	Dados específicos do evento

O schema do payload varia por 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 entrega bem-sucedida.

Resposta	Resultado
2xx	Entregue com sucesso
Non-2xx	Retentativa automática

Estratégia de retentativa

Entregas com falha são retentadas 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 customizadas de retentativa

Retentativas e timeouts podem ser customizados por evento:

WEBHOOK_DICT_INFRACTION_REPORT_MAX_RETRIES=5
WEBHOOK_DICT_INFRACTION_REPORT_REQUEST_TIMEOUT=60s

Proteção por circuit breaker

Para prevenir falhas em cascata, a entrega de webhooks é protegida por um circuit breaker. Quando o Plugin Pix detecta falhas repetidas de entrega (tipicamente respostas 5xx consecutivas ou timeouts), ele temporariamente pausa as chamadas de webhook para o endpoint afetado. Após um período de cooldown configurável, o sistema realiza tentativas controladas de retentativa para verificar se o endpoint se recuperou. Uma vez que respostas bem-sucedidas são detectadas, a entrega normal é retomada automaticamente. Este mecanismo garante:

Proteção contra endpoints sobrecarregados ou instáveis
Recuperação graceful sem intervenção manual
Maior estabilidade geral do sistema em ambientes de produção

O comportamento do circuit breaker funciona junto com retentativas e backoff exponencial, adicionando uma camada extra de segurança para entrega de webhooks.

Boas práticas

Prática	Por que é importante
Ignore campos desconhecidos	Mantenha compatibilidade futura conforme novos campos são adicionados
Processamento idempotente	Use `Idempotency-Key` para evitar processamento duplicado
Confirmação rápida	Retorne `202 Accepted` e processe de forma assíncrona
Processamento assíncrono	Evite bloquear a thread do webhook
Trate compressão	Payloads >1KB são comprimidos com gzip. Verifique o header `Content-Encoding` e descomprima adequadamente

Exemplos de eventos

Abaixo estão exemplos representativos de payloads de webhook que você recebe do Plugin Pix Indireto.

Reivindicação DICT

Eventos de ciclo de vida de propriedade ou portabilidade. Use-os para rastrear 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"
  }
}

Relatório de infração DICT (MED)

Eventos de disputa e sinalização de fraude alinhados com as regras 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 de devolução e decisões relacionadas a casos 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"
  }
}

Cash-in e cash-out de transferência

Eventos de transferência Pix de entrada e saída. 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 para transações Pix. Cash-in de devolução (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"
  }
}

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

Webhooks não são opcionais nas operações de Pix Indireto. Eles são o canal autoritativo para estado de 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, sempre projete consumidores de webhook como sistemas idempotentes, assíncronos e observáveis.

Próximos passos

Agora que você entende como webhooks funcionam no Pix Indireto, explore esses tópicos relacionados:

Como a participação indireta funciona - Configuração e setup inicial
Principais domínios do Pix: transferências - Mergulho profundo nas operações de transferência
Principais domínios do Pix: DICT - Entendendo operações DICT e gestão de chaves
Principais domínios do Pix: MED - Tratamento de disputas e devoluções MED
Referência da API — Documentação completa das APIs de DICT, Claims, Transações, QR Codes e MED

Introdução

CRM

Fees Engine

Pix

Pix Indireto

Pix Direto

Transferência bancária (TED)

Webhooks

Pré-requisitos

Por que 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

Headers

Estrutura do body

Respostas e comportamento de retentativa

Resposta esperada

Estratégia de retentativa

Configurações customizadas de retentativa

Proteção por circuit breaker

Boas práticas

Exemplos de eventos

Reivindicação DICT

Relatório de infração DICT (MED)

Devolução DICT (MED)

Cash-in e cash-out de transferência

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

Conclusão principal

Próximos passos

Introdução

CRM

Fees Engine

Pix

Pix Indireto

Pix Direto

Transferência bancária (TED)

​Pré-requisitos

​Por que 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

​Headers

​Estrutura do body

​Respostas e comportamento de retentativa

​Resposta esperada

​Estratégia de retentativa

​Configurações customizadas de retentativa

​Proteção por circuit breaker

​Boas práticas

​Exemplos de eventos

​Reivindicação DICT

​Relatório de infração DICT (MED)

​Devolução DICT (MED)

​Cash-in e cash-out de transferência

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

​Conclusão principal

​Próximos passos

Pré-requisitos

Por que 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

Headers

Estrutura do body

Respostas e comportamento de retentativa

Resposta esperada

Estratégia de retentativa

Configurações customizadas de retentativa

Proteção por circuit breaker

Boas práticas

Exemplos de eventos

Reivindicação DICT

Relatório de infração DICT (MED)

Devolução DICT (MED)

Cash-in e cash-out de transferência

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

Conclusão principal

Próximos passos