Edición 001Caso técnico
Lo difícil de un webhook no es recibirlo
Una integración de pagos se rompe menos por fallar al recibir eventos que por no saber qué hacer con eventos repetidos, desordenados o ambiguos.
Hay una escena que se repite en muchos equipos: el webhook llega, devuelve 200 y alguien respira tranquilo como si lo difícil ya hubiera pasado.
En pagos, ese momento recién marca el comienzo. El evento puede venir repetido, fuera de orden o con información parcial. Si el sistema no sabe leerlo dentro de una máquina de estados explícita, el costo no aparece como error técnico elegante: aparece como un cobro dudoso, una notificación incorrecta o una reconciliación manual al final del día.
Dónde se rompe de verdad
El problema no es recibir JSON. El problema es traducir una señal externa a una transición válida dentro de tu modelo. Si el proveedor dice "pagado" y vos no distinguís entre autorizado, capturado, conciliado o reversado, la integración se vuelve optimista donde debería ser estricta.
En MiCuota.online esto importa porque el usuario no está mirando la belleza del código. Está esperando saber si su cuota quedó registrada, si la cobranza fue exitosa y si puede confiar en que el sistema no le va a duplicar una acción por un reintento tardío.
La decisión que reduce daño
La decisión útil es tratar el webhook como entrada a una máquina de estados auditable. Cada evento se registra, se valida contra el estado actual y solo entonces produce efectos: marcar un pago, emitir una notificación o actualizar una vista para el usuario.
Eso obliga a modelar idempotencia, correlación y trazabilidad. También obliga a aceptar que algunos eventos deben quedar en cuarentena hasta que el contexto sea suficiente. No todo se resuelve "en línea" ni todo error debe esconderse detrás de un retry ciego.
Qué se puede aplicar mañana
Si hoy tu integración mezcla recepción de eventos, reglas de negocio y notificaciones en el mismo bloque, probablemente estás pagando deuda operativa disfrazada de velocidad.
Separar ingestión, validación y efectos no vuelve al sistema más lento: vuelve más claro quién decidió qué, con qué evidencia y sobre qué estado.
Herramienta práctica
Checklist mínimo para revisar un webhook de pagos
- ¿Existe una máquina de estados explícita para el dominio del pago?
- ¿Cada evento tiene clave de idempotencia o una forma robusta de deduplicación?
- ¿Las transiciones inválidas se registran y quedan visibles para revisar?
- ¿Las notificaciones salen después de confirmar el estado, no antes?
- ¿Hay trazabilidad suficiente para volver del evento a la operación afectada?
Conexión con el ecosistema
El webhook no es una notificación simpática: es un borde operativo donde se decide si un sistema de pagos conserva consistencia o empieza a perder confianza.
Responder este tema¿Cuál es la transición de estado más delicada de tu sistema y por qué hoy sigue dependiendo más de suerte que de diseño?
Julián Engineering Manager, product builder y fundador de Pambú Tech juliancardozo.github.io · LinkedIn
PD: Si estás diseñando suscripciones, cobros o conciliación para Latinoamérica, contame dónde aparece la parte más frágil de la operación.