Saltar al contenido principal
Estos webhooks son esenciales para mantener su sistema sincronizado, especialmente en flujos asíncronos donde una respuesta sola no es suficiente (como confirmación de transacción, cash-in o reversiones).

​
Configuración de webhook

Para recibir webhooks de Pix, su sistema debe:
  • Exponer un endpoint HTTPS público.
  • Responder con estado 200 OK dentro de 5 segundos.
  • Validar y procesar el payload del evento.
  • Opcionalmente verificar la firma del webhook (recomendado)
ImportanteSi su endpoint no responde con 200, reintentaremos el webhook automáticamente usando backoff exponencial con un TTL de 24 horas.

​
Tipos de webhook

Estos son los principales webhooks que podría recibir:

​
pix.transaction.status

Enviado cada vez que el estado de una transacción Pix cambia, típicamente de pendiente a confirmado o fallido. 
{
  "type": "pix.transaction.status",
  "transactionId": "txn_12345",
  "status": "confirmed",
  "amount": 200.00,
  "updatedAt": "2025-07-11T13:00:00Z"
}
CampoDescripción
typeTipo de evento (pix.transaction.status)
transactionIdSu identificador de transacción.
statuspending, confirmed, failed o reversed
amountMonto de la transacción.
updatedAtHora de confirmación del estado final.
ConsejoUse este webhook para actualizar su UI o Ledgers internos. Nunca asuma que una transacción está completa basándose únicamente en la respuesta de la API.

​
pix.cashin.received

Se activa cuando su usuario recibe un Pix de otra institución (cash-in). 
{
  "type": "pix.cashin.received",
  "recipientAccountId": "acc_5678",
  "amount": 950.00,
  "receivedAt": "2025-07-11T11:45:00Z",
  "senderName": "John Smith",
  "senderKey": "[email protected]"
}
  • El plugin de Pix recibe un webhook del PSTI.
  • Verifica la cuenta del destinatario.
  • Acredita el monto a la cuenta.
  • Luego notifica a su sistema con este evento.

​
pix.message.received (MED)

En algunos casos, el PSTI puede enviar mensajes directos al Authorizer. Estos incluyen actualizaciones no vinculadas a una transacción. 
{
  "type": "pix.message.received",
  "content": {
    "messageType": "notice",
    "reference": "ref_234",
    "details": "PSTI maintenance scheduled"
  },
  "receivedAt": "2025-07-11T10:00:00Z"
}
Este tipo de webhook es opcional pero útil para:
  • Reenviar alertas a su equipo.
  • Registrar eventos a nivel del sistema.
  • Activar flujos de trabajo operacionales.

​
pix.reversal.processed

Se activa cuando una reversión Pix se completa con éxito, ya sea por su sistema o debido a un webhook recibido del PSTI. 
{
  "type": "pix.reversal.processed",
  "transactionId": "txn_12345",
  "refundedAmount": 200.00,
  "processedAt": "2025-07-11T13:30:00Z"
}
Esto asegura que pueda:
  • Actualizar saldos internos.
  • Notificar a su usuario.
  • Rastrear el historial completo de reversiones.

​
Comportamiento de reintento

Si su endpoint está caído o devuelve un error, reintentaremos el webhook usando backoff exponencial, con retrasos que aumentan hasta un TTL de 24 horas.
IntentoRetraso antes del reintento
1ºInmediato
2º10 segundos
3º1 minuto
4º5 minutos
…hasta 24 horas

​
Verificar autenticidad

Todas las solicitudes de webhook incluyen el encabezado X-Signature: 
X-Signature: sha256=5f4dcc3b5aa765d61d8327deb882cf99
Para validar:
  • Use su token secreto de webhook.
  • Genere el HMAC SHA256 del cuerpo del payload sin procesar.
  • Compare con el valor en X-Signature.
Esto previene suplantación de identidad o ataques de intermediario.
ConsejoSi está utilizando un framework que analiza JSON antes de leer el cuerpo sin procesar, asegúrese de extraer el cuerpo sin procesar para la verificación de firma.

​
Respuesta recomendada

Para evitar reintentos innecesarios, siempre responda con: 
HTTP/1.1 200 OK
Content-Type: application/json
Opcionalmente, puede devolver: 
{ "status": "received" }

​
Errores comunes

ErrorCómo evitarlo
Asumir que la respuesta de API significa éxito.Siempre espere el webhook pix.transaction.status.
Olvidar verificar la firma.Use X-Signature y su secreto de webhook.
Rechazar webhooks debido a DB lenta o tiempo de espera.Procese de forma asíncrona si es necesario, pero devuelva 200 rápidamente.
Ignorar payloads duplicados.Los webhooks pueden reintentarse. Use transactionId como clave de idempotencia.