Atom PanamáArtículos

Integraciones y pagos

Webhooks de pagos: cómo confirmar el pago antes de marcar la factura como pagada

Qué verificar antes de marcar facturas como pagadas con webhooks de pagos: separar el acuse técnico del asiento, usar la referencia de operación como clave de idempotencia y probar el doble procesamiento antes de activar la automatización.

Atom Panamá ·

Un auditorio lleno durante una conferencia de tecnología

La respuesta corta

No active el marcado automático con la sola llegada del webhook. Adyen, que describe su propia integración, pide aceptar el mensaje con un código 2xx, almacenarlo y procesar su contenido. La biblioteca Amazon Builders' Library advierte que reintentar una operación puede duplicar efectos si no es idempotente. Le proponemos separar el acuse técnico del asiento contable y contabilizar una sola vez por referencia de operación; esa separación es una propuesta de método, no una instrucción de Adyen.

Qué es el acuse y qué es el asiento

Según la documentación de Adyen, un webhook es un mecanismo ligero con el que un servicio de Adyen envía mensajes por HTTP POST a un endpoint que usted define. La guía indica que debe aceptar los webhooks con un código de estado 2xx, almacenar el mensaje y procesar su contenido. Ese es el acuse técnico: confirma recepción y guarda la evidencia.

El asiento financiero es otra cosa. Adyen explica que muchos flujos de pago son asíncronos: el estado final del recurso no se conoce de inmediato tras la solicitud, y el webhook envía el resultado final cuando está disponible. La guía también señala que los mensajes incluyen una instantánea del recurso para que su sistema actualice su estado, y que eventos externos como disputas o la generación de reportes se notifican por webhook.

Le proponemos separar los dos pasos de forma explícita. El acuse responde "recibí y guardé el evento". El asiento responde "esta factura quedó pagada en contabilidad". Si su sistema marca la factura en el mismo instante en que responde 2xx y no almacena el evento, pierde la evidencia con la que podría reintentar la contabilización cuando esta falla. Los extractos que consultamos no establecen si su proveedor reenvía eventos cuando no recibe el 2xx, ni cómo trata notificaciones que llegan tarde; confirme con su proveedor su política de reenvío y revise sus propios registros de llegadas tardías. Esta separación es una propuesta nuestra de método, no una instrucción de Adyen.

El riesgo de procesar dos veces

La biblioteca Amazon Builders' Library, en su artículo sobre reintentos seguros con API idempotentes, afirma que reintentar una llamada como mitigación de un fallo transitorio se basa en un supuesto simplificador: que la operación puede reintentarse sin efectos secundarios. El objetivo es que el resultado ocurra una sola vez, aunque la llamada se repita en el bucle de reintentos. El artículo lo ilustra con un escenario hipotético de lanzamiento de una instancia EC2: reintentar una llamada fallida de creación de un volumen EBS puede terminar en dos volúmenes en lugar de uno.

De ahí sigue una inferencia nuestra, aplicada a su caso: si un webhook de pago dispara el marcado de una factura y el mismo evento se procesa dos veces, ya sea por un reenvío del proveedor o por un reproceso interno, puede registrar el pago dos veces. AWS respalda el riesgo general de duplicar efectos al reintentar; no describe sus sistemas ni afirma que esto le esté ocurriendo. La verificación es suya: revise si hoy existe alguna clave que impida contabilizar dos veces la misma referencia de operación.

Errores transitorios y reintentos

El Centro de arquitectura de Azure, en su guía de errores transitorios, indica que todas las aplicaciones que se comunican con servicios y recursos remotos deben detectar y recuperarse de errores transitorios, y que manejarlos en la capa de aplicación ayuda a evitar fallos en cascada. La guía del patrón Retry del mismo centro detalla que estos errores incluyen la pérdida momentánea de conectividad, la falta de disponibilidad temporal de un servicio y los tiempos de espera cuando el servicio está ocupado. Según esa guía, estos errores normalmente se corrigen automáticamente, y si se repite la acción que los desencadenó tras un retraso adecuado, es probable que tenga éxito.

Esa misma guía describe tres estrategias: cancelar si el error no es transitorio, reintentar de inmediato ante errores inusuales, y reintentar tras una espera cuando el servicio está ocupado, con retrasos crecientes hasta un número máximo de intentos. También recomienda registrar los detalles de los errores y de las operaciones fallidas, y advierte que las solicitudes a distintos servicios pueden necesitar directivas de reintento distintas. La guía señala que muchas bibliotecas de cliente ya traen mecanismos de reintento configurables.

Para su operación esto significa dos verificaciones concretas. Primera: qué hace su sistema cuando el ERP rechaza la contabilización por un error transitorio. Debería reintentar con espera creciente y registrar cada intento. Segunda: si ese reintento es idempotente. Si no lo es, cada reintento puede crear un asiento nuevo. Ambas verificaciones son pasos de diligencia propuestos por nosotros, con base en las guías de Microsoft y AWS.

Ritmo, colas y la dependencia del reenvío

El Centro de arquitectura de Azure, en su patrón de limitación de velocidad, explica que controlar el ritmo de las solicitudes ayuda a mantenerse dentro de los límites del servicio y a minimizar errores de limitación. Su ejemplo numérico es ilustrativo: para ingerir 10 000 registros en Azure Cosmos DB con capacidad de 20 000 unidades de solicitud, un proceso que reenviaba en bloque los rechazados terminó enviando 30 000 registros en total. La guía también advierte que almacenar solicitudes en búfer sin un sistema de mensajería duradero puede perder datos si la aplicación deja de responder.

La aplicación a su caso es una propuesta nuestra. Si su sistema recibe un volumen alto de webhooks y empuja cada uno directo al ERP, puede agotar los límites del ERP y entrar en el ciclo de rechazos y reenvíos que Microsoft describe. Una cola interna o un registro duradero de eventos le permite absorber picos y reintentar la contabilización sin depender de que el proveedor reenvíe el evento. Verifique con su proveedor si reenvía eventos no confirmados, con qué ritmo y durante cuánto tiempo; los extractos que consultamos no establecen el comportamiento de llegadas tardías, así que eso queda como comprobación pendiente con su proveedor y sus propios registros.

Quién decide y quién ejecuta

Le proponemos esta división de responsabilidades, ajustable a su organigrama. Dirección de finanzas o contabilidad define la regla de negocio: un solo asiento por referencia de operación, el mapeo entre evento de pago y factura, y el tratamiento de eventos sin coincidencia. Tecnología responde por el acuse, el almacenamiento del evento, los reintentos y el registro de errores. Dirección general aprueba el cambio y define qué pasa cuando la conciliación detecta una discrepancia.

Traiga a un ingeniero cuando aparezca alguna de estas señales: no existe registro almacenado de los eventos recibidos, la contabilización ocurre dentro del mismo proceso que responde al webhook, no hay forma de probar el doble procesamiento sin tocar producción, o el sistema heredado del ERP no admite una clave única por referencia. En esos casos la automatización directa no es una opción de configuración: es un trabajo de ingeniería sobre la ruta de pago.

Pruebas antes de activar

Antes de marcar facturas en automático, le proponemos tres pruebas con evidencia escrita. Primera: procese dos veces el mismo evento almacenado y confirme que se genera un solo asiento. Segunda: inyecte un evento con una referencia o un monto que no coincida con ninguna factura y confirme que va a un reporte de conciliación, no a un asiento. Tercera: simule una falla de contabilización después del acuse y verifique que el reintento interno completa el asiento sin duplicarlo. Estas pruebas son una propuesta de diligencia derivada del riesgo de duplicación que describe AWS y del flujo de acuse y almacenamiento que describe Adyen.

Lista de verificación

  • Verifique que su endpoint responde 2xx y que el evento queda almacenado; la evidencia es el log del servidor con el código de respuesta y el registro guardado.
  • Confirme que cada evento queda almacenado con su referencia de operación antes de cualquier contabilización; la evidencia es el registro de eventos con la referencia visible.
  • Documente por escrito el mapeo entre evento de pago, factura y referencia de operación; la evidencia es el documento firmado por finanzas y tecnología.
  • Confirme que existe una regla de un solo asiento por referencia de operación; la evidencia es la restricción o validación en el ERP y una captura de su configuración.
  • Procese dos veces el mismo evento almacenado y confirme un solo asiento; la evidencia es el reporte contable con un único registro por referencia.
  • Inyecte un evento con referencia o monto que no coincida con ninguna factura y confirme que va a un reporte de conciliación; la evidencia es el reporte con el evento listado y sin asiento generado.
  • Simule una falla de contabilización después del acuse y verifique que el reintento interno completa el asiento sin duplicarlo; la evidencia es el log de reintentos y el asiento final único.
  • Revise la directiva de reintentos hacia el ERP: número máximo de intentos, retraso entre intentos y registro de cada error; la evidencia es la configuración vigente y una muestra del log.
  • Verifique con su proveedor si reenvía eventos cuando no recibe el 2xx, con qué ritmo y durante cuánto tiempo; la evidencia es la respuesta escrita del proveedor.
  • Revise sus registros de eventos recibidos en busca de llegadas tardías o duplicadas; la evidencia es el conteo de eventos por referencia en un período reciente.
  • Compruebe que existe una cola o registro duradero de eventos si la aplicación se detiene; la evidencia es la prueba de recuperación tras una detención controlada.
  • Revise si el volumen de webhooks en horas pico puede superar los límites del ERP; la evidencia es la medición de eventos por minuto contra el límite documentado del ERP.
  • Asigne por escrito quién responde por el acuse, quién por el asiento y quién por la conciliación; la evidencia es la matriz de responsabilidades aprobada.
  • Defina el criterio para escalar a un ingeniero: falta de registro de eventos, contabilización dentro del proceso del webhook o sistema heredado sin clave única; la evidencia es el criterio documentado y la persona designada.

Preguntas frecuentes

¿Podemos seguir conciliando el asiento a mano aunque recibamos webhooks?

Sí, la decisión de automatizar el asiento es suya. Tenga presente que Adyen describe los webhooks como una característica esencial de una integración exitosa con sus servicios, porque muchos flujos son asíncronos, y como la única forma de recibir notificación automática de algunos eventos externos, como disputas. No automatizar el asiento es distinto de ignorar los webhooks por completo: si los ignora, pierde la notificación del resultado final del pago.

¿Nuestro ERP es compatible con este enfoque?

Las fuentes que consultamos describen integraciones de proveedores y patrones generales, no su ERP. Lo que debe verificar es si su ERP admite una clave única por referencia de operación, de modo que un reintento no cree un asiento nuevo. Eso se comprueba con su proveedor de ERP o con su equipo técnico.

¿Cuánto tarda esta diligencia antes de activar?

Depende de dos factores que usted controla: el acceso a los registros del endpoint y la existencia de un ambiente de pruebas del ERP. Si ambos existen, las tres pruebas y la revisión de reintentos son trabajo acotado para su equipo. Si no hay registro de eventos ni ambiente de pruebas, primero hay que construirlos, y eso ya es un trabajo de ingeniería, no de configuración.

¿Un reenvío del proveedor puede duplicar el pago en nuestros libros?

Si el proveedor reenvía el evento y su procesamiento no es idempotente, el efecto puede duplicarse. AWS advierte que reintentar asume que la operación no tiene efectos secundarios y que el resultado debe ocurrir una sola vez. La duplicación depende tanto de cómo procesa usted cada reenvío como del comportamiento de reenvío del proveedor; se comprueba con la prueba de doble procesamiento y con la respuesta escrita del proveedor sobre su política de reenvío.

¿Qué condiciones cambian el enfoque?

Volumen alto de eventos, presencia de disputas o contracargos, y un sistema heredado sin clave única. Adyen notifica disputas por webhook, así que si su operación las recibe, el mismo canal que marca pagos también le traerá eventos que requieren otro tratamiento contable. Eso amerita reglas separadas por tipo de evento.

Fuentes

  1. Webhooks | Adyen Docs
  2. Making retries safe with idempotent APIs - Amazon Builders' Library
  3. Patrón Retry - Azure Architecture Center
  4. Patrón de limitación de velocidad - Azure Architecture Center
  5. Control de errores transitorios - Azure Architecture Center