Webhooks
Los webhooks te permiten recibir notificaciones en tu servidor cuando ocurre un evento, mediante una solicitud POST a una URL tuya. Es la alternativa a consultar el estado en polling.
Qué necesitás
- Un servidor con una URL pública, accesible por HTTPS, capaz de recibir solicitudes
POST. - Poder responder esa solicitud con
200o201dentro del tiempo de espera. Ver Recibir notificaciones.
Cómo se integra
- Preparás tu endpoint para recibir las notificaciones con el formato que se describe en Recibir notificaciones.
- Creás una suscripción indicando tu URL, el tipo de evento y una clave secreta.
- Validás la firma de cada notificación entrante con esa clave, antes de procesarla.
Guardá el secretKey de forma segura en tu servidor en el momento de crear la suscripción. Lo vas a necesitar para validar cada notificación que recibas, y no se puede recuperar después.
Tipos de evento
| Evento | Se dispara cuando |
|---|---|
NEW_MONEY_MOVEMENT | Se registra un nuevo movimiento de dinero entre cuentas del usuario. |
TRXPULL_AP_TOKEN_GIVEN | Se otorga acceso mediante un token para transferencias pull. |
TRXPULL_WALLET_TOKEN_REVOKED | Se revoca un token de acceso para transferencias pull. |
NEW_MONEY_MOVEMENT es el evento que notifica, entre otros movimientos, los cobros por QR: cuando el movimiento corresponde a un cobro de QR, la notificación incluye el order_id del QR que lo originó.
Los eventos TRXPULL_* corresponden a Open Banking.
Una suscripción por tipo de evento. Cada llamada a Crear suscripción registra un solo evento. Si querés recibir los tres, hacé tres llamadas.
Manejo de errores
Los errores de negocio devuelven HTTP 400 con el siguiente formato:
{
"exceptionType": "Business",
"errors": [
{
"code": "WebHookNotification_InvalidSecretKey",
"description": "La clave secreta no es segura"
}
]
}| HTTP | Código | Cuándo ocurre |
|---|---|---|
| 400 | WebHookNotification_InvalidSecretKey | El secretKey no cumple los requisitos mínimos |
| 400 | WebHookNotification_UndefinedEventType | El tipo de evento indicado no existe |
| 400 | WebHookNotification_SubscriptionNotFound | No hay una suscripción activa para el evento indicado |
| 401 | — | Falta el header Authorization, o el token está vencido o es inválido |
Los errores genéricos comunes a todos los servicios están detallados acá.