Los webhooks son el mecanismo principal que usa el Plugin Pix Indirecto (BTG) para notificarte sobre eventos relacionados con Pix en tiempo real. Recibes callbacks asíncronos y orientados a eventos cuando ocurren cambios en las operaciones Pix: transferencias, devoluciones, reclamaciones de claves o eventos de MED.

Estos webhooks aplican solo al modelo Pix Indirecto vía BTG.Los webhooks de Pix Directo pueden variar según el modelo de conectividad. Una página aparte los documenta.

Requisitos previos

Antes de configurar los webhooks, confirma que tienes:

El Plugin Pix Indirecto configurado y en ejecución (consulta Cómo funciona la participación indirecta)
Un endpoint HTTPS listo para recibir solicitudes de webhook
Conocimiento básico del ciclo de vida de los eventos Pix y de los flujos de transacciones

Qué te dan los webhooks

Los webhooks no son opcionales en las operaciones de Pix Indirecto. Pix es un sistema asíncrono y multipartito. Una solicitud de API puede tener éxito antes de que la transacción llegue a su estado final. El sistema confirma ese estado después, tras la liquidación y la confirmación de la contraparte. Los webhooks permiten que tu sistema:

Sigue el estado autoritativo de las transacciones
Reacciona a devoluciones, reversiones y eventos de MED
Mantén la consistencia del ledger y la operativa
Reduzca el polling y la carga operativa

Tipos de eventos

Recibes eventos agrupados por flujo y entidad, alineados con los dominios de BACEN (Banco Central do Brasil).

Flujo	Entidad	Descripción
DICT	CLAIM	Eventos de portabilidad y de reclamación de titularidad de claves Pix
DICT	INFRACTION_REPORT	Informes de infracción de MED (Mecanismo Especial de Devolução) y ciclo de vida de las disputas
DICT	REFUND	Eventos de solicitud de devolución de MED
DICT	FUNDS_RECOVERY	Cambios de estado de la entidad de recuperación de fondos de MED 2.0 (respaldada en base de datos)
DICT	FUNDS_RECOVERY_EVENTS	Eventos de ciclo de vida de la recuperación de fondos de MED 2.0 (de paso)
DICT	RECONCILIATION_JOB	Cambios de estado del job de conciliación de DICT
TRANSFER	CASHIN	Actualizaciones de estado de los pagos Pix entrantes
TRANSFER	CASHOUT	Actualizaciones de estado de los pagos Pix salientes
REFUND	CASHIN	Actualizaciones de estado de las devoluciones Pix entrantes
REFUND	CASHOUT	Actualizaciones de estado de las devoluciones Pix salientes
RECURRING	AUTHORIZATION_REQUEST · AUTHORIZATION · CHARGE	Eventos de autorización y de cobro de Pix Automático
SCHEDULE	CASHOUT	Eventos de pagos Pix programados
REPORT	TEMPOSTRANSACOES	Eventos del job de informe de tiempos de transacción

Cada evento refleja una transición de estado en el ecosistema Pix. Trata cada evento como la fuente de verdad.

Las dos entidades de MED 2.0 se comportan de forma distinta. El plugin emite FUNDS_RECOVERY después de actualizar su registro local. FUNDS_RECOVERY_EVENTS es de paso: lleva los eventos de ciclo de vida de BTG sin actualización en la base de datos. Consulta MED 2.0: Recuperación de fondos para el flujo completo.

DICT (Diretório de Identificadores de Contas Transacionais) es el directorio de BACEN que gestiona las claves Pix y las operaciones relacionadas, como reclamaciones, infracciones y devoluciones.

Configuración de webhooks

Para habilitar los webhooks, configura las URLs de destino y selecciona qué tipos de evento recibe tu sistema.

Variables de entorno

Puedes configurar los endpoints de webhook en el nivel de entidad, de flujo o global.

Flujo	Entidad	Variable de URL en el nivel de entidad
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`

Las otras entidades siguen el mismo patrón, por ejemplo WEBHOOK_DICT_FUNDS_RECOVERY_EVENTS_URL o WEBHOOK_SCHEDULE_CASHOUT_URL. Cada flujo también tiene una URL en el nivel de flujo para todas sus entidades, WEBHOOK_<FLOW>_URL. El plugin la usa cuando no existe una URL en el nivel de entidad, por ejemplo WEBHOOK_DICT_URL o WEBHOOK_TRANSFER_URL.

El plugin entrega solo los eventos de las entidades que configuras. Define al menos una variable WEBHOOK_<FLOW>_<ENTITY>_* por entidad que quieres recibir, por ejemplo WEBHOOK_DICT_CLAIM_URL o WEBHOOK_DICT_CLAIM_ENABLED=true. Una URL en el nivel de flujo o una URL predeterminada, por sí sola, no activa una entidad.

Prioridad de resolución de URL

Cuando configuras varias URLs, el plugin las resuelve en este orden:

URL en el nivel de entidad Ejemplo: WEBHOOK_DICT_CLAIM_URL
URL en el nivel de flujo Ejemplo: WEBHOOK_DICT_URL
URL predeterminada WEBHOOK_DEFAULT_URL

Formato de la solicitud

Headers

Cada solicitud de webhook incluye headers estandarizados para la trazabilidad.

Header	Descripción
`Content-Type`	`application/json`
`X-Request-ID`	Identificador único de la solicitud
`X-Entity-Type`	Entidad del evento (por ejemplo, `INFRACTION_REPORT`)
`X-Flow-Type`	Dominio de origen (por ejemplo, `DICT`)
`Idempotency-Key`	Identificador único del evento para la deduplicación

Estructura del cuerpo

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

Campo	Descripción
`entityType`	Entidad del evento
`flowType`	Dominio de Pix
`payload`	Datos específicos del evento

El esquema del payload varía según el tipo de evento, pero siempre representa un cambio de estado.

Respuestas y comportamiento de reintento

Respuesta esperada

Tu endpoint debe devolver un estado HTTP 2xx para confirmar la entrega exitosa.

Respuesta	Resultado
2xx	Entregado con éxito
Distinto de 2xx	Se reintenta automáticamente

Estrategia de reintentos

El plugin reintenta automáticamente las entregas fallidas con backoff exponencial (multiplicador predeterminado 2):

Intento	Retraso
1	1 segundo
2	2 segundos
3	4 segundos

Valores predeterminados

Máximo de intentos: 10
Timeout por solicitud: 10 segundos (WEBHOOK_WORKER_TIMEOUT)

Después de que falla el último intento, el plugin mueve el evento a una dead-letter queue para el seguimiento operativo. Para listar los eventos fallidos y enviar uno de nuevo, usa GET /v1/webhooks/outbound y POST /v1/webhooks/outbound/{id}/retry.

Backoff personalizado

Puedes cambiar el multiplicador de backoff por entidad:

WEBHOOK_DICT_INFRACTION_REPORT_BACKOFF_MULTIPLIER=3

Protección con circuit breaker

Un circuit breaker protege la entrega de webhooks y evita fallas en cascada. Cuando el Plugin Pix detecta fallas repetidas de entrega (de forma predeterminada, 5 respuestas 5xx o errores de conexión consecutivos), pausa temporalmente las llamadas de webhook para ese flujo y esa entidad. Después de un período de espera configurable (30 segundos de forma predeterminada), el sistema reintenta el endpoint para verificar si se recuperó. Cuando el endpoint devuelve respuestas exitosas, el plugin reanuda la entrega normal automáticamente.

El circuit breaker funciona junto con los reintentos y el backoff exponencial.

Consultar y reintentar webhooks

El plugin guarda los webhooks que recibe de BTG (entrantes) y los webhooks que te envía (salientes). Usa estos endpoints para encontrar un webhook y procesarlo o enviarlo de nuevo:

Endpoint	Qué hace
`GET /v1/webhooks/inbound`	Lista los webhooks entrantes. El parámetro de query `entity_type` es obligatorio.
`GET /v1/webhooks/inbound/{id}`	Devuelve un webhook entrante.
`POST /v1/webhooks/inbound/{id}/retry`	Procesa de nuevo un webhook entrante `FAILED`. Devuelve `202 Accepted`.
`GET /v1/webhooks/outbound`	Lista los webhooks salientes. El parámetro de query `flow_type` es obligatorio. Un webhook en la cola de dead-letter tiene el estado `DEAD_LETTER`.
`GET /v1/webhooks/outbound/{id}`	Devuelve un webhook saliente.
`POST /v1/webhooks/outbound/{id}/retry`	Envía de nuevo un webhook saliente `FAILED`, `SENT` o `DEAD_LETTER`. Devuelve `202 Accepted`.

Referencia de API: Listar webhooks entrantes · Consultar un webhook entrante · Reintentar un webhook entrante · Listar webhooks salientes · Consultar un webhook saliente · Reintentar un webhook saliente

Errores de transporte y eventos huérfanos

Cuando el plugin recibe una solicitud de devolución de MED, busca la transferencia original a lo largo de la cadena cash-in → cash-out. Si ninguna fuente local coincide, el plugin persiste la devolución como un registro huérfano para la auditabilidad ante BACEN. No descarta la devolución, por lo que el registro queda visible para la conciliación y el seguimiento. Si una consulta de fuente falla en la capa de transporte, el plugin omite esa fuente y continúa. Cuando ninguna fuente se resuelve, el plugin registra la devolución como huérfana. originalEndToEndId es la clave canónica para todas las consultas de devoluciones. El plugin resuelve las devoluciones con este campo en ambos sentidos, cash-in → devolución y cash-out → devolución. Indexa siempre las devoluciones por originalEndToEndId (el ID end-to-end de la transferencia original), no por una única ruta de consulta específica de un sentido.

Informes de transacciones internas (intra-PSP)

El plugin liquida internamente las transferencias intra-PSP (P2P). Nunca llegan a BTG para su liquidación, pero el plugin igual las informa a BACEN mediante la abstracción TRCK002. BTG confirma el estado del informe mediante un webhook CAMT025 que lleva la entidad PixInternalTransactionsReport.

Campo	Descripción
`pactualId`	Identificador del informe asignado por BTG
`clientRequestId`	Tu clave de idempotencia, enviada durante el envío del informe
`entity`	Siempre `PixInternalTransactionsReport`
`status`	`PROCESSING`, `CONFIRMED` o `ERROR`
`errorCode` / `errorDescription`	Se completan cuando `status = ERROR`

El plugin actualiza el estado del informe cuando el webhook de informe CAMT025 confirma o falla. Los webhooks salientes se disparan antes, cuando la transferencia intra-PSP se liquida: TRANSFER / CASHIN para el tramo de cash-in y TRANSFER / CASHOUT para el tramo de cash-out. Para el flujo interno completo, consulta Transferencias intra-PSP. Para listar los informes de transacciones, usa GET /v1/transaction-reports. Si el worker no envió un informe, envíalo con POST /v1/transaction-reports/{id}/submit. El plugin no cambia un informe que ya está en PROCESSING o CONFIRMED. El webhook CAMT025 entrega el resultado.

Referencia de API: Listar informes de transacciones · Enviar un informe de transacciones

Informes de tiempos de transacción (TemposTransacoes)

El plugin calcula los percentiles de experiencia del pagador de TemposTransacoes de BACEN para un mes de referencia cerrado. Para iniciar el cálculo, envía POST /v1/statistics/tempos-transacoes/jobs con el referenceMonth en formato YYYY-MM. El job empieza en PENDING, pasa a RUNNING y termina en COMPLETED o FAILED. Un mes de referencia puede tener un job PENDING o RUNNING a la vez. Para leer el job de un mes, usa GET /v1/statistics/tempos-transacoes/jobs/{referenceMonth}. Cuando el estado es COMPLETED, el campo result trae los percentiles. El plugin también envía un webhook REPORT / TEMPOSTRANSACOES con el resultado cuando el job se completa.

Referencia de API: Crear un job · Listar jobs · Consultar un job · Cancelar un job

Mejores prácticas

Práctica	Por qué importa
Ignora los campos desconocidos	Mantén la compatibilidad con versiones futuras a medida que se agregan campos nuevos
Procesamiento idempotente	Usa `Idempotency-Key` para evitar procesar duplicados
Confirmación rápida	Devuelve `202 Accepted` y procesa de forma asíncrona
Procesamiento asíncrono	Evita bloquear el hilo del webhook
Maneja la compresión	Los payloads de más de 1KB se comprimen con gzip. Revisa el header `Content-Encoding` y descomprime según corresponda

Ejemplos de eventos

Expande cada entrada para ver un payload de ejemplo de ese tipo de evento. Cada ejemplo muestra los campos principales. Un payload puede traer más.

Reclamación DICT

Eventos de ciclo de vida de titularidad o portabilidad. Úsalos para seguir las disputas de claves Pix entre instituciones.

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

Informe de infracción DICT (MED)

Eventos de señalización de disputas y de fraude alineados con las reglas de MED de 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"
  }
}

Devolución DICT (MED)

Solicitudes de devolución y decisiones relacionadas con los 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"
  }
}

Recuperación de fondos DICT (MED 2.0)

Cambios de estado de la entidad de recuperación de fondos. El plugin actualiza su registro local antes de enviar el 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"
  }
}

Los eventos de ciclo de vida llegan como entityType: FUNDS_RECOVERY_EVENTS (de paso, sin actualización en la BD), con valores de payload.body.event como FUNDS_RECOVERY_ANALYSED y FUNDS_RECOVERY_COMPLETED.

Cash-in y cash-out de transferencia

Eventos de transferencias Pix entrantes y salientes.Cash-in (transferencia entrante):

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

{
  "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 y cash-out de devolución

Eventos de liquidación de devoluciones de transacciones Pix.Cash-in de devolución (recibir una devolución):

{
  "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 devolución (enviar una devolución):

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

Dominios principales de Pix: transferencias: Las operaciones de transferencia en detalle
Dominios principales de Pix: DICT: Entender las operaciones de DICT y la gestión de claves
Dominios principales de Pix: MED: Manejo de disputas y devoluciones de MED
MED 2.0: Recuperación de fondos: Recuperación de fraude entre cuentas y sus webhooks
Transferencias intra-PSP: Liquidación P2P interna e informes TRCK002
Referencia de API: Documentación completa de la API para las operaciones de DICT, reclamaciones, transacciones, códigos QR y MED

Introducción

TED Lerian

TED JD

Pix Lerian

Pix JD

JD Courier

Pix BTG

Payments BTG

Webhooks

Requisitos previos

Qué te dan los webhooks

Tipos de eventos

Configuración de webhooks

Variables de entorno

Prioridad de resolución de URL

Formato de la solicitud

Headers

Estructura del cuerpo

Respuestas y comportamiento de reintento

Respuesta esperada

Estrategia de reintentos

Backoff personalizado

Protección con circuit breaker

Consultar y reintentar webhooks

Errores de transporte y eventos huérfanos

Informes de transacciones internas (intra-PSP)

Informes de tiempos de transacción (TemposTransacoes)

Mejores prácticas

Ejemplos de eventos

Próximos pasos

​Requisitos previos

​Qué te dan los webhooks

​Tipos de eventos

​Configuración de webhooks

​Variables de entorno

​Prioridad de resolución de URL

​Formato de la solicitud

​Headers

​Estructura del cuerpo

​Respuestas y comportamiento de reintento

​Respuesta esperada

​Estrategia de reintentos

​Backoff personalizado

​Protección con circuit breaker

​Consultar y reintentar webhooks

​Errores de transporte y eventos huérfanos

​Informes de transacciones internas (intra-PSP)

​Informes de tiempos de transacción (TemposTransacoes)

​Mejores prácticas

​Ejemplos de eventos

​Próximos pasos

Requisitos previos

Qué te dan los webhooks

Tipos de eventos

Configuración de webhooks

Variables de entorno

Prioridad de resolución de URL

Formato de la solicitud

Headers

Estructura del cuerpo

Respuestas y comportamiento de reintento

Respuesta esperada

Estrategia de reintentos

Backoff personalizado

Protección con circuit breaker

Consultar y reintentar webhooks

Errores de transporte y eventos huérfanos

Informes de transacciones internas (intra-PSP)

Informes de tiempos de transacción (TemposTransacoes)

Mejores prácticas

Ejemplos de eventos

Próximos pasos