Saltar al contenido principal
Los webhooks son el mecanismo principal que utiliza el Plugin de Pix Indirecto (BTG) para notificarle sobre eventos relacionados con Pix en tiempo real. En lugar de depender de respuestas síncronas, usted recibe callbacks asíncronos y basados en eventos cada vez que ocurren cambios relevantes en las operaciones Pix — como transferencias, reembolsos, reclamos de claves o eventos relacionados con MED. Este modelo garantiza:
  • Actualizaciones en tiempo casi real
  • Integraciones desacopladas
  • Conciliación confiable y trazabilidad operacional
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 están documentados por separado.

​
Requisitos previos

Antes de configurar los webhooks, asegúrese de tener:
  • El Plugin de Pix Indirecto configurado y en ejecución (consulte Cómo funciona la participación indirecta)
  • Un endpoint HTTPS listo para recibir solicitudes de webhook
  • Comprensión básica del ciclo de vida de eventos Pix y los flujos de transacciones

​
Por qué los webhooks son importantes en Pix

Pix es un sistema asíncrono y multipartito. Incluso cuando una solicitud a la API tiene éxito, el estado final de una transacción solo se confirma posteriormente, después de la liquidación y el reconocimiento de la contraparte. Los webhooks permiten que su sistema:
  • Rastree el estado autoritativo de las transacciones
  • Reaccione a reembolsos, reversiones y eventos MED
  • Mantenga la consistencia contable y operacional
  • Reduzca el polling y la sobrecarga operacional

​
Tipos de eventos

Usted recibe eventos agrupados por flujo y entidad, alineados con los dominios del BACEN (Banco Central do Brasil).
FlujoEntidadDescripción
DICTCLAIMEventos de portabilidad y reclamo de propiedad de claves Pix
DICTINFRACTION_REPORTInformes de infracción MED (Mecanismo Especial de Devolução) y ciclo de vida de disputas
DICTREFUNDEventos de solicitud de reembolso MED
TRANSFERCASHINActualizaciones de estado de pagos Pix entrantes
TRANSFERCASHOUTActualizaciones de estado de pagos Pix salientes
REFUNDCASHINActualizaciones de estado de reembolsos Pix entrantes
REFUNDCASHOUTActualizaciones de estado de reembolsos Pix salientes
Cada evento refleja una transición de estado en el ecosistema Pix y debe tratarse como la fuente de verdad.
DICT (Diretório de Identificadores de Contas Transacionais) es el directorio del BACEN que gestiona las claves Pix y las operaciones relacionadas como reclamos, infracciones y reembolsos.

​
Configuración de webhooks

Usted habilita los webhooks configurando URLs de destino y seleccionando qué tipos de eventos debe recibir su sistema.

​
Variables de entorno

Puede configurar los endpoints de webhook a nivel de entidad, flujo o global.
FlujoEntidadURL de entidadURL de módulo
DICTCLAIMWEBHOOK_DICT_CLAIM_URLWEBHOOK_DICT_URL
DICTINFRACTION_REPORTWEBHOOK_DICT_INFRACTION_REPORT_URLWEBHOOK_DICT_URL
DICTREFUNDWEBHOOK_DICT_REFUND_URLWEBHOOK_DICT_URL
TRANSFERCASHINWEBHOOK_TRANSFER_CASHIN_URLWEBHOOK_TRANSFER_URL
TRANSFERCASHOUTWEBHOOK_TRANSFER_CASHOUT_URLWEBHOOK_TRANSFER_URL
REFUNDCASHINWEBHOOK_REFUND_CASHIN_URLWEBHOOK_REFUND_URL
REFUNDCASHOUTWEBHOOK_REFUND_CASHOUT_URLWEBHOOK_REFUND_URL

​
Prioridad de resolución de URL

Cuando se configuran múltiples URLs, el sistema las resuelve en el siguiente orden:
  1. URL a nivel de entidad Ejemplo: WEBHOOK_DICT_CLAIM_URL
  2. URL a nivel de flujo Ejemplo: WEBHOOK_DICT_URL
  3. URL por defecto WEBHOOK_DEFAULT_URL
Esto le brinda un control granular de enrutamiento sin duplicar infraestructura.

​
Formato de la solicitud

​
Headers

Cada solicitud de webhook incluye headers estandarizados para trazabilidad y seguridad.
HeaderDescripción
Content-Typeapplication/json
X-Request-IDIdentificador único de la solicitud
X-Entity-TypeEntidad del evento (ej. INFRACTION_REPORT)
X-Flow-TypeDominio de origen (ej. DICT)
Idempotency-KeyIdentificador único del evento para deduplicación

​
Estructura del body

{
  "entityType": "INFRACTION_REPORT",
  "flowType": "DICT",
  "payload": {
    ...
  }
}
CampoDescripción
entityTypeEntidad del evento
flowTypeDominio Pix
payloadDatos 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

Su endpoint debe retornar un código de estado HTTP 2xx para confirmar la entrega exitosa.
RespuestaResultado
2xxEntregado exitosamente
No-2xxReintentado automáticamente

​
Estrategia de reintentos

Las entregas fallidas se reintentan automáticamente usando backoff exponencial:
IntentoRetraso
11 segundo
22 segundos
34 segundos
Valores por defecto
  • Máximo de reintentos: 3
  • Timeout por solicitud: 30 segundos
Después de que todos los reintentos fallan, el evento se mueve a una cola de fallos para seguimiento operacional.

​
Configuración personalizada de reintentos

Los reintentos y timeouts se pueden personalizar por evento: 
WEBHOOK_DICT_INFRACTION_REPORT_MAX_RETRIES=5
WEBHOOK_DICT_INFRACTION_REPORT_REQUEST_TIMEOUT=60s

​
Protección por circuit breaker

Para prevenir fallos en cascada, la entrega de webhooks está protegida por un circuit breaker. Cuando el Plugin Pix detecta fallos de entrega repetidos (típicamente respuestas consecutivas 5xx o timeouts), 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 gradual 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, añadiendo una capa de seguridad adicional para la entrega de webhooks.

​
Buenas prácticas

PrácticaPor qué es importante
Ignorar campos desconocidosMantener compatibilidad futura a medida que se añaden nuevos campos
Procesamiento idempotenteUsar Idempotency-Key para evitar procesar duplicados
Confirmación rápidaRetornar 202 Accepted y procesar de forma asíncrona
Procesamiento asíncronoEvitar bloquear el hilo del webhook
Manejar compresiónLos payloads >1KB se comprimen con gzip. Verifique el header Content-Encoding y descomprima según corresponda

​
Ejemplos de eventos

A continuación se presentan ejemplos representativos de payloads de webhook que recibe del Plugin de Pix Indirecto.

​
Reclamo DICT

Eventos del ciclo de vida de propiedad o portabilidad. Úselos para rastrear disputas de claves 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"
  }
}

​
Informe de infracción DICT (MED)

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

​
Transferencia cash-in y cash-out

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

​
Reembolso cash-in y cash-out

Eventos de liquidación de reembolsos para transacciones Pix. Reembolso cash-in (recibiendo 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"
  }
}
Reembolso cash-out (enviando 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, reembolsos y manejo de disputas. Una implementación correcta de webhooks garantiza:
  • Conciliación precisa
  • Cumplimiento regulatorio
  • Resiliencia operacional
  • Experiencia predecible para el cliente
Para entornos de producción, siempre diseñe los consumidores de webhooks como sistemas idempotentes, asíncronos y observables.

​
Próximos pasos

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