Los webhooks son el mecanismo principal que el Plugin de Pix Indirecto (BTG) usa para notificarte en tiempo real sobre eventos relacionados con Pix. En lugar de depender de respuestas síncronas, recibes callbacks asíncronos basados en eventos cada vez que ocurren cambios relevantes en las operaciones de Pix, como transferencias, reembolsos, reclamos de claves o eventos relacionados con MED. Este modelo garantiza:

Actualizaciones casi en tiempo real
Integraciones desacopladas
Conciliación confiable y trazabilidad operativa

Los webhooks descritos en esta página actualmente aplican al modelo de Pix Indirecto a través de BTG.Los webhooks de Pix Directo pueden diferir según el modelo de conectividad y se documentan por separado.

Requisitos previos

Antes de configurar los webhooks, asegúrate de tener:

El Plugin de Pix Indirecto configurado y en funcionamiento (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 de Pix y de los flujos de transacciones

Por qué los webhooks son importantes en Pix

Pix es un sistema asíncrono y multiparte. Incluso cuando una solicitud de API tiene éxito, el estado final de una transacción solo se confirma más tarde, después de la liquidación y del reconocimiento de la contraparte. Los webhooks permiten que tu sistema:

Haga seguimiento del estado autoritativo de la transacción
Reaccione a reembolsos, reversiones y eventos MED
Mantenga la consistencia del libro mayor y 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 de clave Pix y reclamo de titularidad
DICT	INFRACTION_REPORT	Reportes de infracción de MED (Mecanismo Especial de Devolução) y ciclo de vida de disputas
DICT	REFUND	Eventos de solicitud de reembolso de MED
DICT	FUNDS_RECOVERY	Cambios de estado de la entidad Funds Recovery de MED 2.0 (respaldados en base de datos)
DICT	FUNDS_RECOVERY_EVENT	Eventos del ciclo de vida de Funds Recovery de MED 2.0 (pass-through)
TRANSFER	CASHIN	Actualizaciones de estado de pagos Pix entrantes
TRANSFER	CASHOUT	Actualizaciones de estado de pagos Pix salientes
REFUND	CASHIN	Actualizaciones de estado de reembolsos Pix entrantes
REFUND	CASHOUT	Actualizaciones de estado de reembolsos Pix salientes

Cada evento refleja una transición de estado en el ecosistema de Pix y debe tratarse como la fuente de verdad.

Las dos entidades de MED 2.0 se comportan de forma diferente: FUNDS_RECOVERY se emite después de que el plugin actualiza su registro local, mientras que FUNDS_RECOVERY_EVENT es un pass-through de los eventos del ciclo de vida de BTG sin actualización en base de datos. Consulta MED 2.0 — Funds Recovery para ver el flujo completo.

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

Configuración de webhooks

Habilitas los webhooks configurando URLs de destino y seleccionando qué tipos de eventos debe recibir tu sistema.

Variables de entorno

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

Flujo	Entidad	Variable de URL a 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`

Cada flujo también tiene una URL a nivel de flujo que aplica a todas sus entidades cuando no se configura una URL a nivel de entidad: WEBHOOK_DICT_URL, WEBHOOK_TRANSFER_URL y WEBHOOK_REFUND_URL.

Prioridad de resolución de URL

Cuando se configuran múltiples URLs, el sistema las resuelve en el siguiente orden:

URL a nivel de entidad Ejemplo: WEBHOOK_DICT_CLAIM_URL
URL a nivel de flujo Ejemplo: WEBHOOK_DICT_URL
URL por defecto WEBHOOK_DEFAULT_URL

Esto te da un control de enrutamiento granular sin duplicar infraestructura.

Formato de la solicitud

Encabezados

Cada solicitud de webhook incluye encabezados estandarizados para trazabilidad y seguridad.

Encabezado	Descripción
`Content-Type`	`application/json`
`X-Request-ID`	Identificador único de la solicitud
`X-Entity-Type`	Entidad del evento (p. ej. `INFRACTION_REPORT`)
`X-Flow-Type`	Dominio de origen (p. ej. `DICT`)
`Idempotency-Key`	Identificador único del evento para 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 reintentos

Respuesta esperada

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

Respuesta	Resultado
2xx	Entregado con éxito
No-2xx	Reintentado automáticamente

Estrategia de reintentos

Las entregas fallidas se reintentan automáticamente usando backoff exponencial:

Intento	Retraso
1	1 segundo
2	2 segundos
3	4 segundos

Valores por defecto

Máximo de reintentos: 3
Tiempo de espera por solicitud: 30 segundos

Después de que todos los reintentos fallan, el evento se mueve a una cola de fallos para seguimiento operativo.

Configuración personalizada de reintentos

Los reintentos y los tiempos de espera pueden personalizarse por evento:

WEBHOOK_DICT_INFRACTION_REPORT_MAX_RETRIES=5
WEBHOOK_DICT_INFRACTION_REPORT_REQUEST_TIMEOUT=60s

Protección con circuit breaker

Para prevenir fallos en cascada, la entrega de webhooks está protegida por un circuit breaker. Cuando el Plugin de Pix detecta fallos repetidos de entrega (normalmente respuestas 5xx consecutivas o tiempos de espera agotados), pausa temporalmente las llamadas de webhook al endpoint afectado. Después de un período de enfriamiento configurable, el sistema realiza intentos de reintento controlados para verificar si el endpoint se ha recuperado. Una vez que se detectan respuestas exitosas, la entrega normal se reanuda automáticamente. Este mecanismo garantiza:

Protección contra endpoints sobrecargados o inestables
Recuperación elegante sin intervención manual
Mayor estabilidad general del sistema en entornos de producción

El comportamiento del circuit breaker funciona junto con los reintentos y el backoff exponencial, agregando una capa de seguridad adicional para la entrega de webhooks.

Errores de transporte y eventos huérfanos

Un intento de entrega puede fallar en la capa de transporte (conexión rechazada, fallo de DNS, error de handshake TLS) antes de que se devuelva cualquier estado HTTP. Estos fallos se persisten como eventos huérfanos en lugar de perderse, de modo que permanecen visibles para seguimiento operativo y reprocesamiento en lugar de desaparecer silenciosamente. Al gestionar eventos de reembolso, ten en cuenta que las búsquedas de transferencias para cash-in y cash-out de REFUND se ampliaron para resolverse correctamente en ambas direcciones: asegúrate de que tu consumidor indexe los reembolsos por originalEndToEndId en lugar de asumir una única ruta de búsqueda.

Reportes de transacciones internas (intra-PSP)

Las transferencias intra-PSP (P2P) se liquidan internamente y nunca llegan a BTG para su liquidación, pero aún se reportan a BACEN a través de la abstracción TRCK002. BTG confirma el estado del reporte mediante un webhook CAMT025 que lleva la entidad PixInternalTransactionsReport.

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

El plugin actualiza el estado del reporte y, al completarse o fallar, emite los eventos salientes estándar intra-PSP (cashout.completed/cashout.failed, cashin.completed y los equivalentes de reembolso). Para ver el flujo interno completo, consulta Transferencias intra-PSP.

Buenas prácticas

Práctica	Por qué es importante
Ignora campos desconocidos	Mantente compatible hacia adelante a medida que se agregan nuevos campos
Procesamiento idempotente	Usa `Idempotency-Key` para evitar procesar duplicados
Reconocimiento rápido	Devuelve `202 Accepted` y procesa de forma asíncrona
Procesamiento asíncrono	Evita bloquear el hilo del webhook
Gestiona la compresión	Los payloads >1KB se comprimen con gzip. Verifica el encabezado `Content-Encoding` y descomprime en consecuencia

Ejemplos de eventos

A continuación se muestran ejemplos representativos de los payloads de webhook que recibes del Plugin de Pix Indirecto. Expande cada entrada para ver su payload.

Reclamo DICT

Eventos del ciclo de vida de titularidad o portabilidad. Úsalos para hacer seguimiento de las disputas de clave Pix entre instituciones.

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

Reporte de infracción DICT (MED)

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

Reembolso DICT (MED)

Solicitudes y decisiones de reembolso relacionadas con 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"
  }
}

Funds recovery DICT (MED 2.0)

Cambios de estado de la entidad Funds Recovery. El plugin actualiza su registro local antes de reenviar la entidad 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"
  }
}

Los eventos del ciclo de vida llegan como entityType: FUNDS_RECOVERY_EVENT (pass-through, sin actualización en base de datos), con valores de 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": "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 (transferencia saliente):

{
  "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 y cash-out de reembolso

Eventos de liquidación de reembolso para transacciones Pix.Cash-in de reembolso (recibir un reembolso):

{
  "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 reembolso (enviar un reembolso):

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

Conclusión clave

Los webhooks no son opcionales en las operaciones de Pix Indirecto. Son el canal autoritativo para el estado de las transacciones, los reembolsos y la gestión de disputas. Una implementación correcta de webhooks garantiza:

Conciliación precisa
Cumplimiento normativo
Resiliencia operativa
Experiencia del cliente predecible

Para entornos de producción, diseña siempre los consumidores de webhooks como sistemas idempotentes, asíncronos y observables.

Próximos pasos

Ahora que entiendes cómo funcionan los webhooks en Pix Indirecto, explora estos temas relacionados:

Dominios principales de Pix: transferencias - Análisis detallado de las operaciones de transferencia
Dominios principales de Pix: DICT - Comprensión de las operaciones de DICT y la gestión de claves
Dominios principales de Pix: MED - Gestión de disputas y reembolsos de MED
MED 2.0 — Funds Recovery - Recuperación de fondos por fraude entre cuentas y sus webhooks
Transferencias intra-PSP - Liquidación P2P interna y reportes TRCK002
Referencia de API — Documentación completa de la API para operaciones de DICT, Reclamos, Transacciones, Códigos QR y MED

​Requisitos previos

​Por qué los webhooks son importantes en Pix

​Tipos de eventos

​Configuración de webhooks

​Variables de entorno

​Prioridad de resolución de URL

​Formato de la solicitud

​Encabezados

​Estructura del cuerpo

​Respuestas y comportamiento de reintentos

​Respuesta esperada

​Estrategia de reintentos

​Configuración personalizada de reintentos

​Protección con circuit breaker

​Errores de transporte y eventos huérfanos

​Reportes de transacciones internas (intra-PSP)

​Buenas prácticas

​Ejemplos de eventos

​Conclusión clave

​Próximos pasos

Requisitos previos

Por qué los webhooks son importantes en Pix

Tipos de eventos

Configuración de webhooks

Variables de entorno

Prioridad de resolución de URL

Formato de la solicitud

Encabezados

Estructura del cuerpo

Respuestas y comportamiento de reintentos

Respuesta esperada

Estrategia de reintentos

Configuración personalizada de reintentos

Protección con circuit breaker

Errores de transporte y eventos huérfanos

Reportes de transacciones internas (intra-PSP)

Buenas prácticas

Ejemplos de eventos

Conclusión clave

Próximos pasos