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_EVENTS	Eventos de ciclo de vida da Recuperação de Fundos do MED 2.0 (repasse)
DICT	RECONCILIATION_JOB	Mudanças de status do job de conciliação do DICT
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
RECURRING	AUTHORIZATION_REQUEST · AUTHORIZATION · CHARGE	Eventos de autorização e de cobrança do Pix Automático
SCHEDULE	CASHOUT	Eventos de pagamentos Pix agendados
REPORT	TEMPOSTRANSACOES	Eventos do job de relatório de tempos de transação

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_EVENTS é 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`

As outras entidades seguem o mesmo padrão, por exemplo WEBHOOK_DICT_FUNDS_RECOVERY_EVENTS_URL ou WEBHOOK_SCHEDULE_CASHOUT_URL. Cada fluxo também tem uma URL no nível do fluxo para todas as suas entidades, WEBHOOK_<FLOW>_URL. O plugin a usa quando não existe URL no nível da entidade, por exemplo WEBHOOK_DICT_URL ou WEBHOOK_TRANSFER_URL.

O plugin entrega apenas os eventos das entidades que você configura. Defina pelo menos uma variável WEBHOOK_<FLOW>_<ENTITY>_* por entidade que você quer receber, por exemplo WEBHOOK_DICT_CLAIM_URL ou WEBHOOK_DICT_CLAIM_ENABLED=true. Uma URL no nível do fluxo ou uma URL padrão, sozinha, não ativa uma entidade.

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.

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 (multiplicador padrão 2):

Tentativa	Espera
1	1 segundo
2	2 segundos
3	4 segundos

Padrões

Máximo de tentativas: 10
Timeout por requisição: 10 segundos (WEBHOOK_WORKER_TIMEOUT)

Depois que a última tentativa falha, o plugin move o evento para uma dead-letter queue para acompanhamento operacional. Para listar os eventos que falharam e enviar um deles de novo, use GET /v1/webhooks/outbound e POST /v1/webhooks/outbound/{id}/retry.

Backoff customizado

Você pode mudar o multiplicador de backoff por entidade:

WEBHOOK_DICT_INFRACTION_REPORT_BACKOFF_MULTIPLIER=3

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 (por padrão, 5 respostas 5xx ou erros de conexão consecutivos), ele pausa temporariamente as chamadas de webhook para aquele fluxo e aquela entidade. Depois de um período de espera configurável (padrão de 30 segundos), 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.

Consultar e reprocessar webhooks

O plugin guarda os webhooks que recebe do BTG (de entrada) e os webhooks que envia para você (de saída). Use estes endpoints para encontrar um webhook e processá-lo ou enviá-lo de novo:

Endpoint	O que faz
`GET /v1/webhooks/inbound`	Lista os webhooks de entrada. O parâmetro de query `entity_type` é obrigatório.
`GET /v1/webhooks/inbound/{id}`	Retorna um webhook de entrada.
`POST /v1/webhooks/inbound/{id}/retry`	Processa de novo um webhook de entrada `FAILED`. Retorna `202 Accepted`.
`GET /v1/webhooks/outbound`	Lista os webhooks de saída. O parâmetro de query `flow_type` é obrigatório. Um webhook na fila de dead-letter tem o status `DEAD_LETTER`.
`GET /v1/webhooks/outbound/{id}`	Retorna um webhook de saída.
`POST /v1/webhooks/outbound/{id}/retry`	Envia de novo um webhook de saída `FAILED`, `SENT` ou `DEAD_LETTER`. Retorna `202 Accepted`.

Referência da API: Listar webhooks de entrada · Consultar um webhook de entrada · Reprocessar um webhook de entrada · Listar webhooks de saída · Consultar um webhook de saída · Reenviar um webhook de saída

Erros de transporte e eventos órfãos

Quando o plugin recebe uma solicitação de devolução do MED, 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, o plugin registra a devolução como órfã. 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: TRANSFER / CASHIN para a perna de cash-in e TRANSFER / CASHOUT para a perna de cash-out. Para o fluxo interno completo, veja Transferências intra-PSP. Para listar os relatórios de transação, use GET /v1/transaction-reports. Se o worker não enviou um relatório, envie-o com POST /v1/transaction-reports/{id}/submit. O plugin não altera um relatório que já está em PROCESSING ou CONFIRMED. O webhook CAMT025 entrega o resultado.

Referência da API: Listar relatórios de transação · Enviar um relatório de transação

Relatórios de tempos de transação (TemposTransacoes)

O plugin calcula os percentis de experiência do pagador do TemposTransacoes do BACEN para um mês de referência fechado. Para iniciar o cálculo, envie POST /v1/statistics/tempos-transacoes/jobs com o referenceMonth no formato YYYY-MM. O job começa em PENDING, passa para RUNNING e termina em COMPLETED ou FAILED. Um mês de referência pode ter um job PENDING ou RUNNING por vez. Para ver o job de um mês, use GET /v1/statistics/tempos-transacoes/jobs/{referenceMonth}. Quando o status é COMPLETED, o campo result traz os percentis. O plugin também envia um webhook REPORT / TEMPOSTRANSACOES com o resultado quando o job termina.

Referência da API: Criar um job · Listar jobs · Consultar um job · Cancelar um job

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. Cada exemplo mostra os campos principais. Um payload pode trazer mais.

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": "0193a1b2-7c3d-7e4f-8a5b-6c7d8e9f0a1b",
    "accountId": "01989f9e-6508-79f8-9540-835be49fbd0d",
    "externalId": "7f8a9b2c-1234-5678-abcd-ef0123456789",
    "type": "PORTABILITY",
    "status": "CONFIRMED",
    "keyValue": "+5511999998888",
    "keyType": "PHONE",
    "donorParticipant": "87654321",
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-01-15T14:45:00Z",
    "resolutionPeriodEnd": "2024-01-22T14:45:00Z",
    "completionPeriodEnd": "2024-01-29T14: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": "0193a1b2-8d4e-7f50-9b6c-7d8e9f0a1b2c",
    "externalId": "3e4f5a6b-7890-1234-cdef-567890abcdef",
    "accountId": "01989f9e-6508-79f8-9540-835be49fbd0d",
    "transactionId": "E12345678202401151030ABCDEFGHIJK",
    "reason": "REFUND_REQUEST",
    "situationType": "SCAM",
    "status": "OPEN",
    "reporterParticipant": "12345678",
    "counterpartyParticipant": "87654321",
    "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": "0193a1b2-9e5f-7061-8c7d-8e9f0a1b2c3d",
    "externalId": "9a8b7c6d-5432-1098-fedc-ba0987654321",
    "accountId": "01989f9e-6508-79f8-9540-835be49fbd0d",
    "transactionId": "E12345678202401151030ABCDEFGHIJK",
    "infractionReportId": "3e4f5a6b-7890-1234-cdef-567890abcdef",
    "refundReason": "FRAUD",
    "refundAmount": "150",
    "status": "OPEN",
    "requestingParticipant": "12345678",
    "contestedParticipant": "87654321",
    "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 enviar o evento.

{
  "entityType": "FUNDS_RECOVERY",
  "flowType": "DICT",
  "payload": {
    "id": "91d65e98-97c0-4b0f-b577-73625da1f9fc",
    "externalId": "ca1b9c01-ff9e-4a58-90ab-d31512e15ce0",
    "rootTransactionId": "E9999901012341234123412345678900",
    "situationType": "SCAM",
    "status": "CREATED",
    "reporterParticipant": "99999010",
    "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_EVENTS (repasse, sem atualização no banco), com valores de payload.body.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": "550e8400-e29b-41d4-a716-446655440010",
    "amount": "250.00",
    "endToEndId": "E87654321202401151030ABCDEFGHIJK",
    "status": "COMPLETED",
    "type": "CASHIN",
    "source": {
      "account": { "branch": "0001", "number": "987654", "participant": "87654321", "type": "CACC" },
      "owner": { "document": "12345678901", "name": "João Silva", "type": "NATURAL_PERSON" }
    },
    "destination": {
      "key": "maria@example.com",
      "account": { "branch": "0001", "number": "123456", "participant": "12345678", "type": "CACC" },
      "owner": { "document": "98765432100", "name": "Maria Santos", "type": "NATURAL_PERSON" }
    },
    "paymentType": "IMMEDIATE",
    "initiationType": "KEY",
    "urgency": "HIGH",
    "purpose": "TRANSFER",
    "accountId": "01989f9e-6508-79f8-9540-835be49fbd0d",
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-01-15T10:30:05Z"
  }
}

Cash-out (transferência enviada):

{
  "entityType": "CASHOUT",
  "flowType": "TRANSFER",
  "payload": {
    "id": "550e8400-e29b-41d4-a716-446655440020",
    "amount": "500.00",
    "endToEndId": "E12345678202401151045ABCDEFGHIJK",
    "status": "COMPLETED",
    "type": "CASHOUT",
    "source": {
      "account": { "branch": "0001", "number": "123456", "participant": "12345678", "type": "CACC" },
      "owner": { "document": "98765432100", "name": "Maria Santos", "type": "NATURAL_PERSON" }
    },
    "destination": {
      "key": "12345678000199",
      "account": { "branch": "0001", "number": "555000", "participant": "87654321", "type": "CACC" },
      "owner": { "document": "12345678000199", "name": "Empresa ABC Ltda", "type": "LEGAL_PERSON" }
    },
    "paymentType": "IMMEDIATE",
    "initiationType": "KEY",
    "urgency": "HIGH",
    "purpose": "TRANSFER",
    "accountId": "01989f9e-6508-79f8-9540-835be49fbd0d",
    "createdAt": "2024-01-15T10:45:00Z",
    "updatedAt": "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": "550e8400-e29b-41d4-a716-446655440030",
    "originalEndToEndId": "E12345678202401151045ABCDEFGHIJK",
    "returnEndToEndId": "D87654321202401161000ABCDEFGHIJK",
    "amount": "500.00",
    "status": "COMPLETED",
    "type": "CASHIN",
    "accountId": "01989f9e-6508-79f8-9540-835be49fbd0d",
    "createdAt": "2024-01-16T10:00:00Z",
    "updatedAt": "2024-01-16T10:00:02Z"
  }
}

Cash-out de devolução (enviar uma devolução):

{
  "entityType": "CASHOUT",
  "flowType": "REFUND",
  "payload": {
    "id": "550e8400-e29b-41d4-a716-446655440040",
    "originalEndToEndId": "E87654321202401151030ABCDEFGHIJK",
    "returnEndToEndId": "D12345678202401161015ABCDEFGHIJK",
    "amount": "250.00",
    "status": "COMPLETED",
    "type": "CASHOUT",
    "accountId": "01989f9e-6508-79f8-9540-835be49fbd0d",
    "createdAt": "2024-01-16T10:15:00Z",
    "updatedAt": "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

Introdução

TED Lerian

TED JD

Pix Lerian

Pix JD

JD Courier

Pix BTG

Payments BTG

Webhooks

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

Backoff customizado

Proteção por circuit breaker

Consultar e reprocessar webhooks

Erros de transporte e eventos órfãos

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

Relatórios de tempos de transação (TemposTransacoes)

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

​Backoff customizado

​Proteção por circuit breaker

​Consultar e reprocessar webhooks

​Erros de transporte e eventos órfãos

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

​Relatórios de tempos de transação (TemposTransacoes)

​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

Backoff customizado

Proteção por circuit breaker

Consultar e reprocessar webhooks

Erros de transporte e eventos órfãos

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

Relatórios de tempos de transação (TemposTransacoes)

Boas práticas

Exemplos de evento

Próximos passos